Troubleshooting

Applies to: Dispatch v1.0.0, last verified 2026-04-05

TL;DR: Most issues are caused by the server not running, a project not being registered, or the CLI not writing its session file. Check those first.

Non-Claude sessions not appearing

Codex, Copilot, and Gemini sessions are discovered by the multi-session poller, which runs every 30 seconds by default. If a session does not appear:

1. Wait at least 30 seconds after starting the agent.
2. Check the server logs for scanner errors: [multi-session-poller] scanner failed:.
3. Verify the provider’s CLI is installed: codex --version, gemini --version, or gh --version.
4. To reduce the poll interval, set DISPATCH_PROVIDER_POLL_MS=10000 (10 seconds) when starting the server.

Agent shows as idle even though it is running

Dispatch determines liveness from the session JSONL file your CLI writes. If the agent appears idle:

1. Confirm the server is running and the project is registered: node cli.js list
2. Confirm your CLI is writing its session file. Claude Code writes to ~/.claude/projects/<hash>/sessions/<id>.jsonl; Codex, Copilot, and Gemini write to their own home-directory paths. If the file is absent or not being updated, the agent will show as idle.
3. If the session file exists but the agent still shows as idle, check that the file’s mtime is recent. Dispatch uses a 5-minute staleness threshold.

Epic does not appear in the dashboard

Check all three of these:

1. The project is registered: node cli.js list
2. The file exists: .tasks/<epic-name>/plan.md
3. The epic is not archived: the directory must not be inside .tasks/.archive/

Also verify that plan.md has valid YAML frontmatter. The server logs a warning when the phases: key is absent, visible in the terminal where you ran npm run dev.

Dashboard says “Connecting…”

The Dispatch server is not running. Start it:

npm run dev
# or, for production:
npm start

Port conflict (EADDRINUSE)

If npm start or npm run dev fails with Error: listen EADDRINUSE :::4242, another process is already using port 4242.

Find and kill it:

# Find the process using port 4242
lsof -ti:4242
# Kill it
kill $(lsof -ti:4242)

Then start Dispatch again. If you need to run Dispatch on a different port, set the DISPATCH_PORT environment variable:

DISPATCH_PORT=4243 npm run dev

PORT is accepted as a fallback alias, but DISPATCH_PORT is preferred to avoid conflicts with other tools in the same shell environment.

CLI says “DISPATCH server is not running”

The CLI (cli.js) calls the running server’s API. Start the server first, then run CLI commands.

Multiple projects not showing

Each project must be registered separately:

node cli.js add /path/to/project --name "Project Name"
node cli.js list  # verify all projects appear

Activity feed is empty

The activity feed shows structured ActivityEvent objects (phase completions, session events, and agent spawns). Phase completion events are triggered by correctly-formatted entries in execution-log.md. If no agents have completed any phases yet, those events will be absent.

Verify the execution log entry format. Each entry must match:

## [<ISO timestamp>] Phase <id>: <title> — @<persona>

The — character must be an em dash (—, U+2014), not a regular hyphen.

Sessions not appearing under phases

Symptom: You opened a phase in the Epic Drawer or Phase Drawer and the Sessions row is absent. There are no linked sessions, no conversation replay, and no task list from that session.

Three causes, in order of likelihood:

1. Git branch name doesn’t contain the epic slug. Dispatch uses the session’s git branch as the strongest linking signal. The branch must contain the epic’s kebab-case slug (the directory name under .tasks/). For example, if the epic is .tasks/multi-cli-agent-support/, a branch named feat/multi-cli-agent-support will link; a branch named feat/some-other-name will not.

Fix: confirm what branch the agent ran on (visible as a cyan badge on the session card in the Sessions tab), then compare it to the epic name. For future sessions, start the agent on a branch that includes the epic slug.

2. Session JSONL is very old or was deleted. Linking requires the session to exist in Claude Code’s local JSONL history under ~/.claude/projects/. If the file has been pruned or the session is several weeks old, Dispatch has nothing to read.

3. Session ran outside the phase’s temporal window. Phase windows are derived from execution-log.md timestamps. A DONE phase’s window closes at the timestamp of its completion entry. A session that ran significantly before or after that window won’t match, even with a correct branch name. The linker extends IN_PROGRESS phase windows 30 minutes backward to absorb minor timing drift, but large gaps (hours or days) won’t be bridged.

Fix: if the work genuinely happened in that window but the log timestamp is wrong, correct the timestamp in execution-log.md and restart the server to rebuild state.

Phase status not updating

The server uses a polling fallback in addition to file-change events. If a phase update is not appearing:

1. Check the terminal running npm run dev for parse errors on the plan file
2. Confirm the file was saved (some editors write to a temp file and rename; the file watcher handles this but occasional edge cases exist)
3. Wait a few seconds for the polling fallback to pick up the change

Settings were lost after a browser update

Settings are stored in browser localStorage. If the browser cleared local storage, settings revert to defaults. You can restore them by reopening the settings panel and reconfiguring.

How to report a bug

Open an issue on GitHub using the bug report template. Include:

• Node.js version
• OS and version
• Dispatch version or commit hash
• Terminal output from where you ran npm run dev or npm start
• Steps to reproduce

See the Contributing Guide on GitHub for the full issue template. ate.