# Troubleshooting

Canonical HTML: https://getdispatcher.dev/help/troubleshooting

## macOS won’t open Dispatcher

- Right-click the app → **Open**
- Or allow it under **System Settings → Privacy & Security**
- Download only from https://getdispatcher.dev/download

## Windows SmartScreen blocks the installer

- Choose **More info → Run anyway** for the official build
- Confirm the file came from getdispatcher.dev

## Agent harness not detected / “command not found”

1. Verify the CLI in a normal terminal (`claude --version`, `codex --version`, `cursor-agent --version`, etc.)
2. Restart Dispatcher after installing a CLI
3. Ensure the install directory is on your PATH
4. Re-check **Settings → Harnesses**

See install commands in [Agents & harnesses](https://getdispatcher.dev/help/agents).

## Git / worktree errors

- Install Git 2.25+ (`git --version`)
- Run `git worktree list` in the repo to see active worktrees
- Remove a stale worktree: `git worktree remove <path>`
- Clean registration entries: `git worktree prune`
- Don’t check out the same branch in two worktrees

## Dispatcher crashed mid-task

Restart the app. Dispatcher recovers stale workspace locks and re-discovers worktrees on disk. Your branches and worktrees should still be there.

## Integrations won’t connect

- Retry OAuth from **Settings → Integrations** (start Connect from the desktop app, not a bookmark)
- Disable pop-up blockers for the auth window
- Re-authorize if tokens may have expired
- Update Dispatcher if Connect GitHub/Linear still fails after approving in the browser (token is delivered on the local callback)
- For Slack, confirm the bot is invited to the channel

Guides: [GitHub](https://getdispatcher.dev/help/github) · [Linear](https://getdispatcher.dev/help/linear) · [Slack](https://getdispatcher.dev/help/slack)

## Uninstall leftovers

Uninstalling the app does not delete git worktrees. Remove them manually with `git worktree list` / `git worktree remove` / `git worktree prune` if needed.

## Still stuck?

Email **support@getdispatcher.dev** with:

- macOS or Windows (and chip/arch if macOS)
- Dispatcher version
- Steps to reproduce
- Relevant logs or screenshots

Security issues: **security@getdispatcher.dev** (private disclosure only).

Also see [Support & FAQ](https://getdispatcher.dev/support).