--- title: Troubleshooting url: 'https://xcommander.dev/docs/troubleshooting' markdown: 'https://xcommander.dev/docs/troubleshooting.md' date: '2026-11-09' description: "Most problems show up in the menu bar first. Click the hat: the first line of its menu says what XCommander is doing right now. Nothing happens when I press the leader Check, in order: Is Xcode the app in front? XCommander only listens while Xcode is frontmost. The hat's menu says Ready when it is…" --- troubleshooting.md # Troubleshooting Most problems show up in the menu bar first. Click the hat: the first line of its menu says what XCommander is doing right now. ## Nothing happens when I press the leader Check, in order: 1. **Is Xcode the app in front?** XCommander only listens while Xcode is frontmost. The hat's menu says *Ready* when it is. 2. **Is there a warning sign on the hat?** XCommander needs Accessibility permission. Choose **Open Accessibility Settings…** in its menu and turn XCommander on. If it's already on, turn it off and on again. 3. **Is there a lock on the hat?** Another app has turned on *secure input*: a password field somewhere, or **Secure Keyboard Entry** in Terminal or iTerm. While it's on, macOS hides keystrokes from every app. Close the password field or turn the option off. 4. **Is it switched off?** **Leader Key** in the hat's menu must be ticked (the same switch as **Settings → General → Enabled while Xcode is frontmost**). 5. **Is the leader taken?** If you changed it to `⌃SPC` or `⌥SPC`, another app (an input-source switcher, Alfred, Raycast) may get the key first. Try the default, `⌥RET`. ## A key beeps, or a command is missing - **A beep** means Xcode has that command but it's greyed out right now, as it would be in the menu: debugger commands need something running, editor commands need an editor in front. Right after an update, Xcode opens on its Welcome window, where most menus are missing: open a project first. - **A key missing from the panel** means your version of Xcode doesn't have that command at all, so XCommander hides it rather than show a key that can't work. - **Settings → Diagnostics → Check keymap**, or ⌥↩ h c, checks every key against your Xcode's menus and lists anything that no longer finds its command. - If Xcode was just updated, ⌥↩ q r makes XCommander re-read its menus. ## The permission prompt keeps coming back macOS ties the Accessibility permission to the app's signature. This happens when there are **two copies** of XCommander, for example one downloaded and one built from source: each is a different app to macOS. 1. Quit every copy of XCommander. 2. In **System Settings → Privacy & Security → Accessibility**, remove every XCommander entry with the **–** button. 3. Keep only one copy, open it, and grant permission once. Updates installed from inside XCommander keep the permission: they're signed the same way. ## macOS won't open XCommander If macOS says it can't verify XCommander, or that it may be malware, the file didn't come from an official release, or it was damaged on the way. Delete it and download it again from the [releases page](https://github.com/XCommanderDev/XCommander/releases). Each release lists a SHA-256 checksum if you want to check the download: ```sh shasum -a 256 ~/Downloads/XCommander.dmg ``` ## My configuration file doesn't apply - Check the path: `~/.config/xcommander/config.toml`, or `.xcommander.toml` in the project's **root** folder. - The first line must be `version = 1`. - **Settings → Diagnostics → Check config** shows what the last load said. From Terminal, `--check` prints every problem with its line number (see [Configuration](https://xcommander.dev/docs/configuration#when-a-file-has-a-mistake)). - If the file has an error, XCommander keeps the last version that worked, so a fix applies as soon as you save it. ## Updates - **Check for Updates…** in the menu checks straight away. - The daily check can be turned off in **Settings → General**. - If an update fails to install, download the latest version from the [releases page](https://github.com/XCommanderDev/XCommander/releases) and replace the app in Applications. Your settings and permission stay. ## Logs XCommander writes what it's doing to the macOS log. To watch it live, run this in Terminal, then reproduce the problem: ```sh /usr/bin/log stream --level info --predicate 'subsystem == "dev.xcommander.XCommander"' ``` To see the last ten minutes instead: ```sh /usr/bin/log show --last 10m --info --predicate 'subsystem == "dev.xcommander.XCommander"' ``` Type the full `/usr/bin/log`: in zsh, macOS's default shell, a plain `log` is a different, built-in command. The log never contains what you type in your code: XCommander only logs its own keys and commands. ## Reporting a bug **Report a Bug…** in the menu opens a form on GitHub with your XCommander, Xcode and macOS versions already filled in. The most useful reports say what you pressed, what you expected, and what happened instead, and include a few lines of the log above. Ideas are welcome too, on the same [issues page](https://github.com/XCommanderDev/XCommander/issues). --- ## Navigation - Parent: [Documentation](https://xcommander.dev/docs.md) - Previous: [Configuration](https://xcommander.dev/docs/configuration.md) - Next: [How it works](https://xcommander.dev/docs/how-it-works.md)