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.developmentand.env.production, including shell values. Archon’s checkout-root.envthen fills missing values without overriding those that remain. Next,~/.archon/.envoverrides those values, and finally<cwd>/.archon/.envoverrides user scope. Check all three files in that order; a key defined in either.archon/.envfile 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/.envand<cwd>/.archon/.env. See environment file locations and load order for CLI workflow credential exceptions. - Docker: Check the Compose
.envand 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.
Project uses an unexpected provider
Section titled “Project uses an unexpected provider”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_codebasesSET ai_assistant_type = NULLWHERE 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.
Bot Not Responding
Section titled “Bot Not Responding”Check if the application is running:
If running locally:
# Check the server processcurl 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 appVerify bot token:
grep TELEGRAM_BOT_TOKEN /path/to/env-fileTest with health check:
curl http://localhost:3090/health# Expected: {"status":"ok"}Database Connection Errors
Section titled “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_URLecho $DATABASE_URL
# Test connection directlypsql $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_messagesClone Command Fails
Section titled “Clone Command Fails”Verify GitHub token:
grep GH_TOKEN /path/to/env-file# Should have both GH_TOKEN and GITHUB_TOKEN setTest token validity:
# Test GitHub API accesscurl -H "Authorization: token $GH_TOKEN" https://api.github.com/userCheck 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-repoGitHub Webhook Not Triggering
Section titled “GitHub Webhook Not Triggering”Verify webhook delivery:
- Go to your webhook settings in GitHub
- Click on the webhook
- Check “Recent Deliveries” tab
- Look for successful deliveries (green checkmark)
Check webhook secret:
grep WEBHOOK_SECRET /path/to/env-file# Must match exactly what you entered in GitHubVerify ngrok is running (local dev):
# Check ngrok statuscurl http://localhost:4040/api/tunnels# Or visit http://localhost:4040 in browserCheck application logs for webhook processing:
Local:
# Look for GitHub-related log lines in server outputDocker:
docker compose logs -f app | grep GitHubPort Conflicts
Section titled “Port Conflicts”Check if port 3090 is already in use:
macOS/Linux:
lsof -i :3090Windows:
netstat -ano | findstr :3090You can override the port with the PORT environment variable:
PORT=4000 bun run devWhen 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)
Section titled “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 :3090Note 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 12345If multiple stale processes are present:
taskkill /F /IM bun.exetaskkill /F /IM node.exeSee also: Windows Setup for more Windows-specific guidance.
E2E Testing / agent-browser
Section titled “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-browseragent-browser installagent-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.jsagent-browser open http://localhost:3090Docker
Section titled “Docker”These issues are specific to running Archon inside Docker containers.
Container Won’t Start
Section titled “Container Won’t Start”Check logs for specific errors:
docker compose logs appVerify environment variables:
# Check if .env is properly formatteddocker compose configRebuild without cache:
docker compose build --no-cachedocker compose up -dIf using the with-db profile, add --profile with-db to the above commands.
Docker Database Issues
Section titled “Docker Database Issues”For local PostgreSQL (with-db profile):
# Check if postgres container is runningdocker compose --profile with-db ps postgres
# Check postgres logsdocker compose logs -f postgres
# Test direct connectiondocker 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_messagesDocker Clone Issues
Section titled “Docker Clone Issues”Check workspace permissions inside the container:
docker compose exec app ls -la /.archon/workspacesTry 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
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 bereachable 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:
# macOS / Linux / WSLcurl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)irm https://claude.ai/install.ps1 | iexIf Claude Code is installed somewhere else, such as through npm, set CLAUDE_BIN_PATH to it:
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/claudeWhen 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:
ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS=120000 archon workflow run ...Running
archonfrom 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
Section titled “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.
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:
archon workflow run archon-investigate --project owner/repo --cwd /other/clone --no-worktreeUse 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.gitfile at that path points somewhere unexpected (submodule, malformed). Inspect it withcat <path>/.gitand clean up manually.Cannot verify worktree ownership: filesystem permission or I/O error reading<path>/.git. Checkls -la <path>and file permissions on~/.archon/workspaces.
Legacy nested GitLab storage recovery
Section titled “Legacy nested GitLab storage recovery”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:
/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./worktree removeis 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 reportsThis 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.
Stored project path is relative
Section titled “Stored project path is relative”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/projectFor 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.
