Error codes
Every user-facing error the Coherent CLI throws carries a stable COHERENT_E0NN code. The code never changes across releases once allocated. Each entry below shows when you see the error, why it fires, and how to fix it.
- COHERENT_E001
No AI key available
`coherent chat` makes API calls to Anthropic (or OpenAI) directly. If no key is configured, the command cannot proceed.
- COHERENT_E002
Another coherent session is active
Coherent holds a project-wide lock (`.coherent.lock`) between `session start` and `session end` so two runs cannot corrupt shared state. The lock is shared by both the chat rail and the skill rail.
- COHERENT_E003
`coherent _phase ingest` received empty stdin
The ingest step parses the AI response from stdin. When the pipe is empty, there is nothing to parse and the phase cannot advance.
- COHERENT_E004
Phase-engine protocol mismatch
The skill markdown (`.claude/skills/coherent-generate/SKILL.md`) embeds the protocol version it was written against. The CLI advances its protocol when the phase-engine contract changes. A mismatch means the two disagree on artifact shapes, command output, or ingest parsers — running anyway would silently corrupt the session.
- COHERENT_E005
Session schema version mismatch
Sessions are ephemeral by design — they hold in-progress phase artifacts, not long-term state. Across CLI upgrades the session schema may change. Rather than auto-migrating (complex and risky), the CLI rejects the mismatched session and asks you to start a new one.
- COHERENT_E006
Session artifact missing on resume
The session-resume flow detects a session in `awaiting-ingest` status but the expected input artifact (e.g. `anchor-input.json`, `pages-input.json`) is absent. A previous run wrote the session marker but failed to persist the artifact downstream phases need.
- COHERENT_E007
applyMode: no-new-ai received an AI-dependent request without pre-populated output
The skill rail (`/coherent-chat` via Claude Code) and the API rail (`coherent chat`) share the same `applyRequests` entry point but run with different `applyMode` settings. API rail has an AI provider available and runs in `with-ai` mode — non-pre-populated AI requests are fine, the provider fills in the output mid-dispatch. Skill rail has NO provider and runs in `no-new-ai` mode — every AI-dependent request must arrive with its output already filled in by the upstream skill phase. Pre-v0.12.0 the skill rail silently dropped these requests; since v0.12.0 it throws E007 loudly so the producer-side bug surfaces immediately.
- COHERENT_E008
Project was created with an older Coherent version than the installed CLI
The CLI's config schema, generator templates, and validator rules evolve across releases. A project initialized with an older CLI may have a config shape that the newer CLI's downstream code doesn't expect — e.g., a missing field on a page that the new generator dereferences. Pre-v0.13.1 the CLI printed a soft warning and continued, leading to cryptic generic `TypeError` mid-generation. v0.13.1 makes this a hard stop at config-load time so the actionable fix shows BEFORE any state mutation.