Troubleshooting

Common issues and their solutions when running Archon.

Bot Not Responding

Check if the application is running:

If running locally:

# Check the server process
curl http://localhost:3090/health
# Expected: {"status":"ok"}

If running via Docker:

docker compose ps
# Should show 'app' with state 'Up'

Check application logs:

Local:

# Server logs are printed to stdout when running `bun run dev`

Docker:

docker compose logs -f app

Verify bot token:

# In your .env file
cat .env | grep TELEGRAM_BOT_TOKEN

Test with health check:

curl http://localhost:3090/health
# Expected: {"status":"ok"}

Database Connection Errors

Check database health:

curl http://localhost:3090/health/db
# Expected: {"status":"ok","database":"connected"}

For SQLite (default):

SQLite requires no setup. The database is created automatically at ~/.archon/archon.db. If you see errors, check that the ~/.archon/ directory exists and is writable.

For remote PostgreSQL:

# Verify DATABASE_URL
echo $DATABASE_URL

# Test connection directly
psql $DATABASE_URL -c "SELECT 1"

Verify tables exist (PostgreSQL):

psql $DATABASE_URL -c "\dt"

# Should show: remote_agent_codebases, remote_agent_conversations, remote_agent_sessions,
# remote_agent_isolation_environments, remote_agent_workflow_runs, remote_agent_workflow_events,
# remote_agent_messages

Clone Command Fails

Verify GitHub token:

cat .env | grep GH_TOKEN
# Should have both GH_TOKEN and GITHUB_TOKEN set

Test token validity:

# Test GitHub API access
curl -H "Authorization: token $GH_TOKEN" https://api.github.com/user

Check workspace permissions:

The workspace directory is ~/.archon/workspaces/ by default (or /.archon/workspaces/ in Docker). Make sure it exists and is writable.

Try manual clone:

git clone https://github.com/user/repo ~/.archon/workspaces/test-repo

GitHub Webhook Not Triggering

Verify webhook delivery:

1. Go to your webhook settings in GitHub
2. Click on the webhook
3. Check “Recent Deliveries” tab
4. Look for successful deliveries (green checkmark)

Check webhook secret:

cat .env | grep WEBHOOK_SECRET
# Must match exactly what you entered in GitHub

Verify ngrok is running (local dev):

# Check ngrok status
curl http://localhost:4040/api/tunnels
# Or visit http://localhost:4040 in browser

Check application logs for webhook processing:

Local:

# Look for GitHub-related log lines in server output

Docker:

docker compose logs -f app | grep GitHub

Port Conflicts

Check if port 3090 is already in use:

macOS/Linux:

lsof -i :3090

Windows:

netstat -ano | findstr :3090

You can override the port with the PORT environment variable:

PORT=4000 bun run dev

When running in a git worktree, Archon automatically allocates a unique port (3190-4089 range) so you don’t need to worry about conflicts with the main instance.

Stale Processes (Windows)

Symptom: The Web UI shows a spinning indicator with no response, and the terminal shows no activity — even though you’ve started bun run dev.

Cause: A previous bun or node process is still holding the port. This is common on Windows when the terminal is closed without stopping the server.

Diagnose:

netstat -ano | findstr :3090

Note the PID in the last column, then verify which process it is:

tasklist | findstr 12345

(Replace 12345 with the actual PID.)

Fix — kill by PID (preferred):

taskkill /F /PID 12345

If multiple stale processes are present:

taskkill /F /IM bun.exe
taskkill /F /IM node.exe

Caution

Do not kill claude.exe processes — those are active Claude Code sessions.

See also: Windows Setup for more Windows-specific guidance.

E2E Testing / agent-browser

agent-browser: command not found:

agent-browser is an optional external dependency — see the E2E Testing Guide for installation.

npm install -g agent-browser
agent-browser install

agent-browser daemon fails to start (Windows):

agent-browser has a known Windows bug. Use WSL as a workaround — see E2E Testing on WSL.

agent-browser daemon fails to start (macOS/Linux):

Kill stale daemons and retry:

pkill -f daemon.js
agent-browser open http://localhost:3090

Docker

These issues are specific to running Archon inside Docker containers.

Container Won’t Start

Check logs for specific errors:

docker compose logs app

Verify environment variables:

# Check if .env is properly formatted
docker compose config

Rebuild without cache:

docker compose build --no-cache
docker compose up -d

If using the with-db profile, add --profile with-db to the above commands.

Docker Database Issues

For local PostgreSQL (with-db profile):

# Check if postgres container is running
docker compose --profile with-db ps postgres

# Check postgres logs
docker compose logs -f postgres

# Test direct connection
docker compose exec postgres psql -U postgres -c "SELECT 1"

Verify tables exist (Docker PostgreSQL):

docker compose exec postgres psql -U postgres -d remote_coding_agent -c "\dt"

# Should show: remote_agent_codebases, remote_agent_conversations, remote_agent_sessions,
# remote_agent_isolation_environments, remote_agent_workflow_runs, remote_agent_workflow_events,
# remote_agent_messages

Docker Clone Issues

Check workspace permissions inside the container:

docker compose exec app ls -la /.archon/workspaces

Try manual clone inside the container:

docker compose exec app git clone https://github.com/user/repo /.archon/workspaces/test-repo

“Claude Code not found” When Running Compiled Binary

Symptom: A workflow that uses Claude fails with:

Claude Code not found. Archon requires the Claude Code executable to be
reachable at a configured path in compiled builds.

Cause: Compiled Archon binaries (archon from the curl/PowerShell installer or Homebrew) do not bundle Claude Code. They need an explicit path to the Claude Code executable. Source/dev mode (bun run) auto-resolves via node_modules and is unaffected.

Fix: Install Claude Code separately and point Archon at it.

# macOS / Linux / WSL — Anthropic's recommended native installer
curl -fsSL https://claude.ai/install.sh | bash
export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
$env:CLAUDE_BIN_PATH = "$env:USERPROFILE\.local\bin\claude.exe"

For a durable setup, set the path in ~/.archon/config.yaml instead:

assistants:
  claude:
    claudeBinaryPath: /absolute/path/to/claude

archon setup auto-detects and writes CLAUDE_BIN_PATH for you. After setup, run archon doctor to confirm the binary actually spawns. Docker users do not need to do anything — the image pre-sets the variable.

See the AI Assistants → Binary path configuration guide for the full install matrix.

Workflows Time Out Waiting for the First Event

Symptom: A workflow node produces no output and eventually fails on a first-event timeout.

Cause: A slow environment (cold model, constrained machine) can exceed the default 60-second wait for the AI provider’s first event.

Fix: Raise the timeout:

ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS=120000 archon workflow run ...

Running archon from inside a Claude Code session (or another coding agent) is a supported, normal way to drive Archon — it no longer emits a warning.

Worktree Belongs to a Different Clone

Symptom: Running a workflow (especially with --branch <name>) from one local clone surfaces one of these errors:

• Worktree at <path> belongs to a different clone (<other-clone-path>). Remove it from that clone or use a different codebase registration.
• Cannot verify worktree ownership at <path>: <reason>
• Cannot adopt <path>: path contains a full git checkout, not a worktree.
• Cannot adopt <path>: .git pointer is not a git-worktree reference.

Cause: Archon derives codebase identity from the remote URL (owner/repo), so two local clones of the same remote share one codebase_id. Worktrees are stored under a shared path (~/.archon/workspaces/<owner>/<repo>/worktrees/), which means a worktree created by clone A is visible on disk from clone B. The isolation system refuses to silently adopt across clones because it would operate on the wrong filesystem state.

Fix — pick one:

1. Remove the other clone’s worktree. If you no longer need the other clone’s in-progress work:

   # From the other clone's directory, find and remove the conflicting worktree
   archon isolation list
   archon complete <branch-name>          # graceful cleanup
   # or, if no work to preserve:
   git worktree remove <path> --force

2. Use a different branch name for this run so the two clones don’t compete for the same worktree path:

   archon workflow run <name> --branch <different-name> "task"

3. Work from a single clone. If both local checkouts are for the same project, consolidate to one. Archon’s codebase registration currently assumes one local path per remote; true multi-clone support is tracked in #1192.

Other variants:

• path contains a full git checkout, not a worktree: something non-Archon created a full git repo at the worktree path. Remove or move it.
• .git pointer is not a git-worktree reference: the .git file at that path points somewhere unexpected (submodule, malformed). Inspect it with cat <path>/.git and clean up manually.
• Cannot verify worktree ownership: filesystem permission or I/O error reading <path>/.git. Check ls -la <path> and file permissions on ~/.archon/workspaces.

Chat Says the Working Directory No Longer Exists

Symptom: A chat message in a project-scoped conversation is refused with:

• This conversation's working directory no longer exists: <path>

Cause: The conversation carries a working-directory override (cwd) pointing at a directory that has since been removed — an isolated worktree torn down by archon isolation cleanup, the periodic reaper, the Environments list in the web UI, or your own rm -rf. The override outlives the directory. Only workflow runs re-resolve isolation; a chat turn uses the recorded path as-is.

Archon refuses the turn instead of passing the missing path to the AI provider. It does not silently fall back to the project root, because relocating the agent into the live checkout would widen its write scope without you asking for it. Before this check existed, the provider spawned into the missing directory and the failure surfaced as an unrelated error — posix_spawn reports a missing working directory as ENOENT against the executable’s path, so Codex reported No such file or directory (os error 2) and Claude reported a libc/architecture mismatch. Neither named the directory.

Fix — follow the message:

1. /setproject <name> clears the stale override and rebinds the conversation to a project. This always works and is the suggestion you will always be offered.
2. /worktree remove is offered only when the conversation is still bound to an isolation environment. It detaches and returns you to the project root. When the environment reference has already been cleared, this command reports This conversation is not using a worktree., which is why it is not suggested in that state.

The refusal writes nothing and changes no state, so a transient cause (a mount blip, a directory mid-move) costs one refused message and nothing else — the next turn re-evaluates from scratch. Operators can find these events in the logs under orchestrator.conversation_cwd_missing, which records the conversation id, the path, and the isolation environment id.