Troubleshooting

This page aggregates common failures when using Backlog.md. Each section is organized as "Symptom → Cause → Remedy". Detailed explanations for each feature remain on their original pages; this page only serves as a troubleshooting index and remedy guide.

Web Port Occupied

Symptom: port unavailable when starting backlog browser, or the address does not open.

Cause: default port 6420 is already used by another process.

Remedy:

• By default autoPort: true; when the port is occupied, the server automatically scans for the next available port and prints the real address in the terminal (such as http://localhost:6421). Copy the console output; this is not a failure.
• If autoPort is disabled, an occupied port raises an EADDRINUSE error—explicitly specify a port with backlog browser --port 8080.
• Automatic scanning only accepts ports within the user port range (1024–65535) and refuses random high ports assigned by the OS.

See Startup & Access and the Web UI section of Configuration Management.

Graph Stuck Building / Lock Conflict

Symptom: graph page shows loading for a long time, /api/graph keeps returning building; or a lock conflict is reported on startup.

Cause: a graph slot lock can only be held by one process at a time. When the holder process has exited, the lock is automatically reclaimed and will not get stuck building; stuck building usually means the holder process is still alive (for example another browser session or a residual backlog browser process).

Remedy:

• If the holder process has exited, no action is needed; the lock is reclaimed and rebuilt automatically.
• If the holder is still alive, the interactive terminal asks whether to take over the lock—confirm only after ensuring the old process no longer needs the graph.
• Two browser sessions each hold independent databases (partitioned by project path hash) and do not contend; when troubleshooting, confirm whether multiple service processes were started for the same project.
• The cache directory can be overridden with the environment variable BACKLOG_GRAPH_CACHE_DIR; BACKLOG_GRAPH_BACKEND=kuzu is no longer a valid value (native dependency removed); the only valid override is memory.
• When Cypher search is unavailable (graph page finds nothing, backlog graph query errors), first check the terminal for the warning [graph] RyuGraph (WASM) backend init failed for <path>, falling back to memory: if present, the backend has degraded to memory (no Cypher). Distinguish "path not visible to WASM" (fixed in v1.53.9) from "engine error" (needs reporting) based on the reason at the end of the warning.

Watch / File Changes Not Refreshing

Symptom: TUI board, Web interface, or task list --json --watch does not reflect recent changes.

Cause and Remedy:

• TUI board: uses Bun.watch to listen to the tasks directory. It is resilient to atomic writes (waits for the file to stabilize before refreshing), but confirm you modified the backlog/ directory of the current project—instances started with --cwd / BACKLOG_CWD only watch their own resolved project.
• --json --watch: notifications are advisory; a 1-second reconcile tick uses file stat signatures as a fallback to repair missed events; if the signature has not changed, output is not repeated. Confirm the listening process's upstream program is still alive (it stops when the launcher exits).
• Web interface: refreshes via WebSocket broadcasts. If the whole page does not refresh, first confirm the WebSocket connection is normal in the browser console; writes from CLI / TUI / MCP all trigger notifications.

macOS Illegal Hardware Instruction / Architecture Mismatch

Symptom (M-series Mac): running backlog reports illegal hardware instruction or Binary package not installed for darwin-....

Cause: Node, Bun, or Homebrew is running under Rosetta (x64 emulation), but an Intel binary incompatible with the native CPU architecture is installed.

Remedy: first check the architecture reported by each tool:

uname -m                            # arm64 = Apple Silicon hardware; x86_64 = Intel or Rosetta shell
node -p process.arch                # Node/Bun runtime architecture
sysctl -in sysctl.proc_translated   # 1 = current shell is running under Rosetta
which brew                          # /opt/homebrew = arm64 brew, /usr/local = Intel brew

If architectures are inconsistent, reinstall with the native architecture:

brew reinstall backlog-md                    # upstream formula; first confirm `which brew` outputs /opt/homebrew
arch -arm64 npm i -g @kuwork/backlog.md
arch -arm64 bun add -g @kuwork/backlog.md

Deliberately running x64 Node under Rosetta also works: the launcher falls back to whichever backlog.md-darwin-* package is actually installed. See Installation & Initialization for details.

Watch Process Spinning at High CPU (Older Versions)

Symptom: backlog task list --json --watch continuously consumes high CPU even when nothing is happening (about 35–42% in large repositories).

Cause: older versions' 1-second reconcile tick unconditionally repeated full task-list reads; cost grows with repository size.

Remedy: upgrade to the latest version—when idle, it only performs a cheap stat-signature comparison per second, reducing CPU to below 1%, with unchanged output and latency. Browser and TUI watchers do not use this polling and are unaffected.

MCP Connection Issues

Symptom: AI client reports MCP server startup failure, timeout, or tasks being written to the wrong project.

Remedy: see the "Frequently Asked Questions" section of MCP Workflow:

• Startup failure / timeout: usually the local backlog command resolves to a stale binary—rebuild, register with the codex mcp add backlog -- backlog mcp start format, and test backlog mcp start separately.
• Writing to the wrong project: upgrade to the latest version (server follows client workspace roots), or use backlog mcp start --cwd <path> to lock the directory.

Pressing E to Open Editor Freezes

Symptom: in TUI / Web, pressing E to open the editor hangs or the editor does not start.

Cause and Remedy: common with the default editor code --wait, which can hang unattended agent processes, or editor paths containing arguments failing to parse.

• Clear the default editor: backlog config set defaultEditor ""
• Or override per command with the EDITOR environment variable: EDITOR=nvim backlog board
• If the editor path contains arguments, write the full executable path or use a wrapper script; set TERM=xterm-256color for color issues.

See the "Editor resolution priority" section of Configuration Management.