Troubleshooting

Nothing happens when I launch it

Check Task Manager for an XTop.exe that is already running. The app only allows one copy, so a second launch hands over to the running one and closes itself — which looks exactly like nothing happening. The running copy will have opened its panel.

If the app cannot start at all, it shows an error box instead of failing silently: a window that will not load, or a data file that will not read, gives you a dialog with the details and the path to the data folder.

The tray icon is missing

Windows decides whether a tray icon sits on the taskbar or in the hidden-icons overflow. Drag it out of the ^ area, or set it under Settings → Personalization → Taskbar → Other system tray icons.

The island disappeared

If you unplugged the monitor it was on, it pins itself back onto a visible display automatically.

Otherwise, check three things in Settings: Show the island may be off, Auto-hide the island may be on (it is tucked into the edge — point at the sliver), or Island position may be an edge you were not looking at.

The tray icon and Ctrl+Shift+Space work either way. If the island failed to load altogether, the tray menu offers Restore island.

X says no AI tool is installed

X runs the AI command-line tool you already have — it has none of its own. Open the chat, click the name at the top left, and use Install next to Claude, ChatGPT, Gemini or OpenCode: a terminal opens with the command ready.

If a tool is installed but shows no green dot, XTop could not find it on PATH, on Windows or inside WSL. Open a terminal and run the tool's name by hand to check. If it is found but every answer fails, use Sign in — the tool needs your account once.

The terminal takes no keyboard input

The interactive part of the terminal could not load, so sessions show output only. The terminal window says so in a banner. Commands still run and their output still appears — you just cannot type into them.

WSL options are greyed out

The app checks WSL and tells you what it found: not installed, the Microsoft Store placeholder instead of the real thing, or installed with no distro set up. The disabled entries say which, with a link to Microsoft's install page.

If the check could not be sure, nothing is disabled — better to let you try than to block you on a guess.

If a specific distro is missing, check the name in Settings → WSL distro against wsl -l -v.

Prayer times are wrong or missing

• Times are fetched once a day and cached. Refresh times in the Islamic dialog forces a re-fetch — do that after travelling.
• Check the calculation method; it changes Fajr and Isha by a lot.
• No connection on the first run of the day means no times for that day. Once cached, a dropped connection does not stop the alerts.

No sound

Settings tells you when it played something and nothing came out. Check the Windows volume mixer — XTop can be muted there on its own, separately from the system volume. Also check that the sound for that kind of alert is not set to Silent.

Meetings

Covered in detail at the end of the Meetings page. The short version:

• "Choose or download a local Whisper model first" — open Manage model… and download one.
• "The Whisper server stopped unexpectedly" — recording keeps going; press record again to restart transcription.
• A non-ASCII model path — Whisper cannot open it. Keep models in C:\ProgramData\XTop\models.
• "N segments behind" from the start of every meeting — the engine cannot keep up with the room. The app handles this itself: it closes any whisper server left over from an earlier run before starting a new one (two running at once was the usual cause), and lowers the quality — priming first, then model size — instead of letting the queue fill up. If it still cannot keep up, your machine cannot run this model live: pick a lighter one for recording and run Improve transcript afterwards.
• "Transcription has stalled" — the engine stopped answering and was restarted. The recording is not affected; the missing part comes back with Improve transcript.
• "The transcription engine stopped unexpectedly", especially right after pressing Improve transcript — usually the model file is damaged. whisper.cpp does not reject a file of the wrong size: it reads the start of it and exits without a word. So model files are checked against their published size before the engine starts, and a damaged one is named as damaged and downloaded again. The reason the engine gave is also written to %APPDATA%\XTop\logs\main.log.

"Start with Windows" is disabled

The toggle only works for an installed build. If you are running the portable exe, install the setup version instead and turn it on there.

I restored the wrong backup

Your previous data was archived before the restore, into a before-restore folder inside %APPDATA%\XTop\. Restore from there.

The data file is corrupt

XTop moves it aside as xtop-db.json.corrupt-<timestamp> and starts fresh instead of deleting it. If you have a backup, restore it; if not, the corrupt file is still there to salvage by hand.