Troubleshooting · Dispatcher Docs

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”

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

See install commands in Agents & harnesses.

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 · Linear · 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.