Skip to main content

Troubleshooting

Common errors and fixes. If yours isn't here, open an issue — we'll add it.

DaemonLockHeld when running axon​

✗ Another daemon process holds the lock (PID 12345, started at 2026-05-27T14:00:00Z)

Cause: another axon daemon (or Axon Desktop) is already running against the same ~/.axon/ directory.

Fix:

  • If you intended to run the CLI: quit Axon Desktop first (tray menu → Quit Axon)
  • If a previous daemon crashed and left a stale lock: confirm with ps -p <PID>, then delete ~/.axon/daemon.pid and retry

Dashboard window opens blank (Electron)​

Cause: usually a stale dashboard build mismatching the daemon's expected assets, or a renderer-side JS error.

Fix:

  1. View → Toggle Developer Tools, check Console for red errors
  2. If you see "Failed to fetch": daemon isn't running — check the terminal where pnpm start is logged
  3. If you built from source: rebuild the chain — pnpm --filter @axon-trading/dashboard build && pnpm --filter @axon-trading/cli build && pnpm --filter @axon-trading/desktop build

Mode switch hangs on "Restarting…"​

Cause: the daemon either failed to restart cleanly or the dashboard isn't picking up the new bearer token.

Fix:

  • Look at the daemon log (terminal where pnpm start is running, or Console.app filtered to Axon)
  • Common cause: live-mode config is invalid (bad RPC URL, builder address). Switch back to demo, fix config in Settings → Live trading configuration, then try again.
  • Force a hard reload of the dashboard: ⌘R (browser) or right-click → Reload (Electron)

MCP server not connecting in agent runtime​

Cause: usually the agent runtime can't find the axon binary, or the daemon isn't running.

Fix:

  1. Run axon (or open Axon Desktop) — daemon must be running for MCP tool calls to succeed
  2. Check the runtime's MCP config file (paths vary per runtime — see Connect Agent)
  3. Verify axon install --verify reports the path is resolvable
  4. Restart your agent runtime after running axon install

"Couldn't run diagnostics: Failed to fetch" in dashboard​

Cause: dashboard's bearer token is stale (daemon restarted, token rotated).

Fix:

  • Hard reload (⌘R) — dashboard re-fetches /v1/session/refresh to get the new token
  • If that doesn't work, reopen the dashboard from axon dashboard or from the desktop tray

macOS "Axon is damaged and can't be opened"​

Cause: Gatekeeper rejecting the unsigned download.

Fix:

xattr -cr "/Applications/Axon.app"

This removes the quarantine attribute Safari/curl set on the download. Then right-click → Open → Open the first time.

Port 47890 already in use​

Cause: another process — usually a forgotten axon daemon, or a totally unrelated service.

Fix:

lsof -ti:47890                    # see the PID
lsof -ti:47890 | xargs kill       # nuke it if you're sure

Or set a different port: AXON_PORT=47891 axon.

"Cannot find module 'better-sqlite3'" on Desktop​

Cause: native module wasn't rebuilt against Electron's Node ABI.

Fix (from source):

cd packages/desktop
./node_modules/.bin/electron-rebuild -f -w better-sqlite3

If installing from a release tarball, the native binary should be prebuilt — file an issue if it's missing for your platform.

node-gyp fails: "no such file or directory: '2/axon-terminal/...'"​

Cause: your repo clone path contains a space (e.g. ~/Documents/GitHub 2/). node-gyp doesn't handle spaces in build paths.

Fix: move the clone to a no-space path:

mv "~/Documents/GitHub 2/axon-terminal" "~/code/axon-terminal"
cd ~/code/axon-terminal && pnpm install

(better-sqlite3 ships prebuilt binaries and isn't affected — only electron-installer-dmg's macos-alias transitive dep needs compilation locally.)

Strategy install fails with STRATEGY_SIGNER_NOT_PINNED​

Cause: you built @axon-trading/cli from source without the Strykr ed25519 public key inlined, so the daemon refuses to install Strykr-signed strategies.

Fix:

  • Use a published @axon-trading/cli from npm (the Strykr-published binaries inline the pinned pubkey)
  • OR install your own strategies signed with your own key (set AXON_PUBLISHED_STRYKR_PUBKEY at build time)

Auto-update notification but nothing happens​

For unsigned macOS builds, Apple blocks automatic installation. The notification opens the GitHub Releases page — download the new .dmg manually.

Signed v1.0+ will support seamless auto-install. Track #auto-update.

Audit log "chain break" error​

AuditTamperError: chain break at row 12345

Cause: the audit DB's hash chain is inconsistent. Almost always caused by concurrent writers (two daemons running against the same ~/.axon/ — should now be prevented by the daemon lock, but possible on older versions).

Fix:

  • Inspect the row: sqlite3 ~/.axon/audit.db "SELECT * FROM audit_log WHERE id = 12345"
  • If it's a benign break (no actual tamper), recover: axon audit rebuild-chain --confirm
  • If you suspect tamper: archive + start fresh: axon audit reset --confirm (you keep the archived DB for forensics)

Anything else​

Open an issue with:

  • Your platform (OS, arch, version)
  • axon --version
  • Steps to reproduce
  • Daemon log output (terminal or Console.app filtered to "Axon")
  • DevTools console output (for dashboard issues)