Troubleshooting

Start with:

coven doctor

doctor is the fastest readiness check for the store, current project, daemon, and installed harnesses. Follow the first failing branch instead of changing multiple parts of the system at once.

Recovery rules

Use the same rules at every stage of the first-session journey:

Fix the first failing branch coven doctor reports, then rerun doctor.
Inspect before you mutate. Session show, events, logs, and status are read-only; sacrifice is permanent.
Keep the recovery path aligned with the stage that failed.

Journey stage	Start here
Install or `PATH`	`coven` command not found
Harness install or login	Harness missing
Daemon startup or connection	Daemon unavailable
Recorded run or project boundary	`cwd` rejected
Session inspection or lifecycle	Stale running sessions and Archive, summon, and sacrifice

Return to Getting started after the failing stage passes. Do not change unrelated configuration while the first failure is still unresolved.

Rendering diagram…

Error code lookup

Daemon and API failures use a structured error envelope. Branch on error.code, not message wording.

You see	Start here
`not_found`	Verify the route and API version.
`invalid_request`	Compare the body with the local API contract and check ids and field casing. If the message says `cwd` is outside the project root, see `cwd` rejected.
`session_not_found`	Run `coven sessions --all`; the id may be stale, deleted, or stored under another `COVEN_HOME`.
`session_not_live`	See Session does not accept input.
`project_root_violation`	Reserved. Current daemons report a `cwd` outside the project root as `invalid_request`; see `cwd` rejected.
`forbidden` or `AUTHORITY_REQUIRED` (`403`)	Send the request over the local IPC endpoint, not the optional TCP listener. See Optional loopback TCP.
`pty_spawn_failed`	See Harness missing.
`runtime_unavailable`	See Daemon unavailable.
`internal_error`	Restart the daemon, preserve relevant logs, and report a reproducible case.

The envelope shape and privacy rules are in Error envelope.

`coven` command not found

Use the dedicated install-debugging decision tree. For a one-off readiness check before repairing PATH:

npx @opencoven/cli doctor

A source checkout can run:

cargo run -p coven-cli -- doctor

Harness missing

coven doctor prints an install hint for every built-in harness. Install and authenticate the one you selected, then rerun doctor.

npm install -g @openai/codex
codex login

npm install -g @anthropic-ai/claude-code
claude doctor

Use Harness troubleshooting for adapter, binary, and provider-authentication failures.

Daemon unavailable

coven daemon start
coven daemon status
coven daemon restart

If a client still cannot connect, verify it resolves the same COVEN_HOME and platform IPC endpoint as the CLI. Continue with Daemon recovery and upgrades when the socket, lock, or service manager is stale.

Stale running sessions

A session record can still say running after its harness is gone. Coven moves it to orphaned in two ways:

While the daemon runs. About every 30 seconds, the daemon checks the sessions it launched. A session loses its harness once the daemon no longer tracks it as live or, on macOS and Linux, once the harness's process group is gone. After two minutes of that without a recorded exit, the session becomes orphaned, and the daemon notes its id in the recovery log. Windows has no process-group check, so a dead harness whose session is still tracked as live stays running until the next start.
On the next daemon start. Every record left running becomes orphaned, except externally registered sessions. This includes sessions started with coven run, which the running daemon does not check.

Externally registered sessions keep the status their owner reports. If a harness reports its exit late, the record takes that outcome instead of orphaned.

coven sessions --all

Inspect the record and log. Archive it when the evidence should remain, or sacrifice it only when permanent deletion is intended.

Session does not accept input

Input works only for a live daemon-owned session. Completed, failed, killed, archived, external, or orphaned sessions remain inspection and replay surfaces; they do not become live again merely because a client attaches.

Use:

coven sessions show <session-id>
coven sessions events <session-id> --limit 100
coven sessions log <session-id>

`cwd` rejected

Coven rejects a working directory that canonicalizes outside the project root.

Use a path inside the project:

coven run codex "inspect package" --cwd packages/cli

Do not use parent traversal or a symlink escape. Read Project roots for the complete boundary.

API version rejected

Check the named contract first:

GET /api/v1/health

A route-prefix value alone does not prove every capability exists. Update Coven or the client until their named contracts overlap, then branch on advertised capabilities.

`coven sessions` printed a table

The browser opens only in an interactive terminal.

Force browser mode:

coven sessions --manage

Force table mode:

coven sessions --plain

Archive, summon, and sacrifice

Archive hides a non-running session and keeps its events.
Summon restores an archived record to the active list.
Sacrifice permanently deletes a non-running session and its events.

The rituals cheat sheet records allowed states and reversibility.

Machine pressure

When doctor is healthy but local work remains slow, inspect the host without launching a harness:

coven pc status
coven pc top --n 10
coven pc disk

Mutating relief commands require explicit confirmation. Read the coven pc reference before using them.

Still stuck

Use Support to collect a small evidence packet, redact private data, and choose the right issue or community route.

Contributor failures

Repository secret scanning, formatting, generated-output, and test failures are maintainer workflow rather than end-user runtime recovery. Follow the coven repository contribution guide for runtime work and this repository's CONTRIBUTING.md for documentation work.

On this page