Skip to content

Troubleshooting

Common issues and their solutions when running Archon.

For credential checks below, trace the value Archon actually uses rather than checking only one file:

  • Source server: Start with the environment inherited by the server. Boot strips every key named in the CWD’s .env, .env.local, .env.development and .env.production, including shell values. Archon’s checkout-root .env then fills missing values without overriding those that remain. Next, ~/.archon/.env overrides those values, and finally <cwd>/.archon/.env overrides user scope. Check all three files in that order; a key defined in either .archon/.env file wins over earlier sources, even if empty. CWD means the server’s working directory, which may differ from the checkout.
  • CLI or compiled server: Skip the checkout-root file. Check the inherited environment after CWD key stripping, then ~/.archon/.env and <cwd>/.archon/.env. See environment file locations and load order for CLI workflow credential exceptions.
  • Docker: Check the Compose .env and the container environment, then the container’s Archon env files in the same user/repo order. See Docker configuration.

Replace /path/to/env-file in each command with each applicable file above. A missing key in one file does not mean it is unset in Archon. Shell commands such as the GitHub API test use your current shell’s value; set it to the effective credential you traced before testing.

Codex credential preflight fails while other Codex work succeeds

Section titled “Codex credential preflight fails while other Codex work succeeds”

Multiple Codex processes can try to refresh the same native ChatGPT login. One process may keep a rejected refresh token after another has saved a working login, causing a credential check to report “no usable login”.

Archon rechecks that result once in a fresh Codex process, using the same caller deadline and requesting a refresh again. When the second read returns a status, it logs codex.native_login_rechecked with only the resulting credential state. The recheck does not bypass authentication or send a model request. If the recheck errors, times out or returns a malformed response, the check is inconclusive: the run starts with a credential_check_inconclusive warning, as any inconclusive credential check does.

For host execution, run archon doctor under the same OS user and environment as the server. Doctor checks only the configured host assistant. When that assistant is Codex, its Assistant login line must read codex: usable to show the native login works. A line reading codex: uses the credential connected in Archon means doctor skipped the native check because an openai credential is connected; it says nothing about the native login. If the native login remains unavailable, run codex login under that user and environment and check again. codex login status alone does not prove that a refresh will succeed.

Codex does not support workflow container execution (containerExec: false). Run Codex workflows on the host: omit --container and disable any effective workflow or global/project configuration container.enabled setting. See the container selection rules. Repairing container credentials does not enable this capability. See container provider support.

A host credential preflight refusal before run creation leaves no run to resume: repeat the original archon workflow run command after fixing the login.

New projects follow the configured provider when a conversation is created: repository .archon/config.yaml assistant:, global defaultAssistant, DEFAULT_AI_ASSISTANT, then the first registered built-in provider. .claude and .codex directories no longer select a provider. Set assistant: in repository configuration to choose one.

Projects registered by older versions retain their stored provider. Upgrades cannot distinguish an explicit choice from a registration-time snapshot, so they preserve all stored values. To let one of these projects follow configuration, find its ID and clear only that project’s choice in your SQLite or PostgreSQL database:

SELECT id, name, ai_assistant_type FROM remote_agent_codebases;
UPDATE remote_agent_codebases
SET ai_assistant_type = NULL
WHERE id = '<project-id>';

This affects new conversations. Existing conversations retain the provider recorded when they were created. Older Archon binaries can still open the database, but resolve a project’s NULL choice to Claude instead of the configured default on downgrade.

Check if the application is running:

If running locally:

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

If running via Docker:

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

Check application logs:

Local:

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

Docker:

Terminal window
docker compose logs -f app

Verify bot token:

Terminal window
grep TELEGRAM_BOT_TOKEN /path/to/env-file

Test with health check:

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

Check database health:

Terminal window
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:

Terminal window
# Verify DATABASE_URL
echo $DATABASE_URL
# Test connection directly
psql $DATABASE_URL -c "SELECT 1"

Verify tables exist (PostgreSQL):

Terminal window
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

Verify GitHub token:

Terminal window
grep GH_TOKEN /path/to/env-file
# Should have both GH_TOKEN and GITHUB_TOKEN set

Test token validity:

Terminal window
# 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:

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

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:

Terminal window
grep WEBHOOK_SECRET /path/to/env-file
# Must match exactly what you entered in GitHub

Verify ngrok is running (local dev):

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

Check application logs for webhook processing:

Local:

Terminal window
# Look for GitHub-related log lines in server output

Docker:

Terminal window
docker compose logs -f app | grep GitHub

Check if port 3090 is already in use:

macOS/Linux:

Terminal window
lsof -i :3090

Windows:

Terminal window
netstat -ano | findstr :3090

You can override the port with the PORT environment variable:

Terminal window
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.

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:

Terminal window
netstat -ano | findstr :3090

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

Terminal window
tasklist | findstr 12345

(Replace 12345 with the actual PID.)

Fix — kill by PID (preferred):

Terminal window
taskkill /F /PID 12345

If multiple stale processes are present:

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

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

agent-browser: command not found:

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

Terminal window
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:

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

These issues are specific to running Archon inside Docker containers.

Check logs for specific errors:

Terminal window
docker compose logs app

Verify environment variables:

Terminal window
# Check if .env is properly formatted
docker compose config

Rebuild without cache:

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

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

For local PostgreSQL (with-db profile):

Terminal window
# 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):

Terminal window
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

Check workspace permissions inside the container:

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

Try manual clone inside the container:

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

“Claude Code not found” When Running Compiled Binary

Section titled ““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 look for it at the native installer’s path (~/.local/bin/claude, or %USERPROFILE%\.local\bin\claude.exe on Windows) unless CLAUDE_BIN_PATH or assistants.claude.claudeBinaryPath points elsewhere. This error means no pin is set and that path holds no executable. An invalid pin fails with a different error that names the setting (CLAUDE_BIN_PATH is set to ... but the file does not exist), in every mode and without falling back to autodetection; correct or remove that setting. Source/dev mode (bun run) with no pin resolves Claude Code through node_modules.

Fix: Install Claude Code with the native installer, which Archon then finds on its own:

Terminal window
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

If Claude Code is installed somewhere else, such as through npm, set CLAUDE_BIN_PATH to it:

Terminal window
export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"

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

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

When Claude is selected, setup auto-detects and writes CLAUDE_BIN_PATH for you. Run archon setup --providers claude to select Claude and configure its path. 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

Section titled “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:

Terminal window
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.

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.

Registration refusal: Project "<name>" is already registered at <path> means this is another clone of a registered remote. Two clones of one remote cannot be separate Archon projects. Run from the named registered checkout and use --branch or git worktree add for parallel checkouts. For a fresh run from the separate clone, bind it to the existing project instead:

Terminal window
archon workflow run archon-investigate --project owner/repo --cwd /other/clone --no-worktree

Use archon project list to find the registered name or ID. --no-worktree executes in the clone; isolated execution uses the registered checkout. See workflow run. Removing a worktree or changing the branch name does not resolve a registration refusal.

Inspect the run with archon workflow get <full-run-id>, or run archon workflow runs from the registered checkout. From the separate clone, workflow runs falls back to an install-wide list limited to 20 rows by default.

If this checkout replaces a moved or retired checkout, use /update-project "<name>" <new-absolute-path> to repair the registration. Keep its existing workspace storage: it contains state, artifacts and logs. For legacy nested GitLab projects, follow the storage recovery steps below before changing the path.

Ownership errors: Older registrations or manually changed worktrees can still produce the ownership errors above. Inspect git worktree list from the registered checkout and the checkout named in the error. Preserve in-progress work and use the registered checkout’s worktree. Only remove an obsolete worktree from its owning checkout after confirming it is no longer needed. Archon refuses to adopt worktrees from another clone.

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.

A legacy GitLab project whose registered name has more than two segments (for example group/subgroup/api) derives its storage root from the basename of its registered checkout path, rather than from its name. Its root is $ARCHON_HOME/workspaces/_local/<checkout-basename> (ARCHON_HOME defaults to ~/.archon). This also applies when the saved checkout is an old worktree: a path ending in worktrees/old-api uses _local/old-api.

Restoring the original checkout at its saved path preserves that storage root. Archon refuses automatic repair when it cannot preserve the root.

If you must move the checkout, identify and back up the existing storage root before using /update-project. Work out the destination root from the new checkout’s basename and migrate the existing state, artifacts and logs there as part of the move. Do not overwrite another project’s storage at that destination. A path update alone does not move storage: changing the basename can hide the existing state or select a root already used by another project. Keep the original storage until you have verified the recovered project can see its state and history.

Chat Says the Working Directory No Longer Exists

Section titled “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.

Project base branch points at an old local branch

Section titled “Project base branch points at an old local branch”

Older registrations stored whichever local branch was checked out. Existing stored values are preserved because Archon cannot distinguish a past choice from a detected snapshot. New registrations store only an explicit choice; NULL follows the remote default when needed. The engine reads the remote’s live HEAD advertisement, so a renamed default is picked up without refreshing local origin/HEAD. An unreachable remote or unknown HEAD fails resolution with configuration guidance rather than guessing a branch.

Until project settings support editing this value, look up the project in your database:

SELECT id, name, default_branch FROM remote_agent_codebases;

To make that project follow its remote default, replace the ID below with the selected ID:

UPDATE remote_agent_codebases SET default_branch = NULL WHERE id = '<project-id>';

This leaves other projects unchanged. worktree.baseBranch in .archon/config.yaml still outranks the project choice, and --base overrides the base for a single dispatch. --base-branch is for initial CLI registration, not editing an existing project. No database migration is needed: older binaries already accept NULL as auto-detection, although they retain their older cached remote-HEAD behavior.

Workflow runs and isolation cleanup reject a registration whose stored default_cwd is not absolute before using that path for Git or removing environments. The error names the project and gives a recovery command. Changing the invocation directory does not repair the registration.

In Archon chat, supply the project’s actual absolute path:

/register-project "my-project" /absolute/path/to/project

For a legacy relative path, automatic repair detects the kind from the replacement path and preserves the registration’s ID, settings, and history. Repair refuses a path or kind change that would move Archon storage or worktrees, including cross-run state and repo-local worktrees configured with worktree.path. Use a replacement path and kind that keep those locations unchanged. Use /register-project --folder "my-project" /absolute/path/to/project to keep a folder project as a folder even when the path contains a Git repository. Archon does not guess a replacement or rewrite legacy rows automatically.