Troubleshooting

Start with the host logs, then check the dependency, address, or provider involved.

The host reports an old SQLite version

Install SQLite 3.51 or newer. On Apple Silicon macOS, the host checks the Homebrew library at /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib.

For another location, set ACPDASH_SQLITE_LIB to the actual shared-library file before starting the host. Checking sqlite3 --version only checks that executable, not necessarily the library Bun loaded.

A port is already in use

The dashboard defaults to port 4317 and previews to 4318. A running host or Tailscale Serve may already use the port you selected. Start a separate instance with two free ports and its own storage, or stop the existing instance you intend to replace.

The dashboard opens but an agent fails

Run the chosen provider from a terminal as the host account. Check its authentication, executable path, and adapter. A service does not necessarily inherit your interactive shell’s PATH.

Review the stopped run’s error in the conversation. Correct the setup before resuming it. See the provider table for executable overrides.

Changes do not appear

The host serves the built frontend. Rebuild it after web changes and refresh the browser:

bun run build

Restart the host after backend changes. Starting bun run dev alone does not provide the complete application because it does not start or proxy the host API.

Find the service logs

On macOS:

launchctl print "gui/$(id -u)/local.acpdash"
tail -f ~/.local/share/acpdash/service.log

On Linux:

systemctl --user status acpdash.service
journalctl --user -u acpdash.service -f

The service depends on the checkout staying at its installed path. If it moved, reinstall the service from its new location.

Previews fail on another device

Check that the preview origin resolves and is reachable from that device. A loopback URL refers to the client itself. The preview and dashboard also need different hostnames. Review preview configuration.

A check has no attempts remaining

Open the Needs you request for the exhausted check. Write corrective feedback as your own answer to that question to restore the configured number of attempts. An ordinary chat message, a pull request comment, or a new commit does not reset it.

If you chose Pause or Stop, explicitly resume the agent to reopen the question, then answer it. Resume alone does not restore attempts. If the count has reset but work is still held, check for a project pause, another unanswered question, or a pending permission.

Passing runs do not erase earlier failed attempts. See preflight and retries for exactly which executions count.

A result is still waiting

Open the result and inspect its current verification and closeout status. It may need user approval, fresh proof for a changed pull request head, a required command, an independent review, CI, or resolved review threads.

Do not assume a finished conversation means its result has been accepted. The verification guide explains those separate states.

Report a problem

Include the repository commit, operating system, Bun version, provider, steps to reproduce, and the relevant error. Remove credentials, private hostnames, and sensitive project content before posting logs or screenshots to the issue tracker.