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.

npm / nvm / `~/.local/bin` mismatch

If npm install -g succeeds but your terminal still says command not found: claude or codex:

You may have npm_config_prefix or prefix= in ~/.npmrc pointing globals at ~/.local while your shell never added ~/.local/bin to PATH.
nvm prints nvm is not compatible with the "npm_config_prefix" environment variable when both are configured.

Dispatcher resolves harness CLIs the same way an interactive terminal would (login-shell PATH, npm global bin dir, ~/.local/bin, nvm, Homebrew, etc.) and launches agents by absolute path, so agents should run even when your shell PATH is incomplete.

To fix your terminal too (recommended):

unset npm_config_prefix          # remove any prefix= line from ~/.npmrc as well
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code @openai/codex
which claude codex

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.

When opening a Slack / deep-link issue that lives on another board (or has no board):

Dispatcher switches the board filter to the issue’s board, or
If the issue is unassigned and you already have a board selected, it adds the issue to that board
The issue popup shows the board name, plus Switch to … / Move to … if you’re still on a different board

Slack task link does not open the desktop app

Safari “cannot open the page because the address is invalid” means macOS has no handler for dispatcher://.

Install or update from https://getdispatcher.dev/download (need 0.1.31+; deep links are not in older builds)
Open Dispatcher once from Applications (so Launch Services registers the scheme)
Retry the Slack link or Open desktop app
Quick check in Terminal: open 'dispatcher://tasks/<issue-id>' — the app should open a popup for that issue
If you only land on the tasks list, update past 0.1.36 (task popup) and confirm the same organization owns the Slack task

Being signed in on getdispatcher.dev does not launch the desktop app. Use Open in browser until a current desktop build is installed.

Also see Slack.

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.