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 Hang Silently When Run Inside Claude Code

Symptom: Workflows started from within a Claude Code session (e.g., via the Terminal tool) produce no output, or the CLI emits a warning about CLAUDECODE=1 before the workflow hangs.

Cause: Nested Claude Code sessions can deadlock — the outer session waits for tool results that the inner session never delivers.

Fix: Run archon serve from a regular shell outside Claude Code and use the Web UI or HTTP API instead.

Suppress the warning: If you have a non-deadlocking setup and want to silence the warning:

ARCHON_SUPPRESS_NESTED_CLAUDE_WARNING=1 archon workflow run ...

Adjust the timeout: If your environment is slow and hitting the 60-second first-event timeout:

ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS=120000 archon workflow run ...

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.