Error reference

Hone Environments never show you a stack trace. Every failure is a named error with a stable code and a one-line, actionable message. The CLI catches these and renders just the message, exiting 1. Anything unexpected exits 2. In code, errors are thrown by providers and detected with isAsymmetricError(e); each carries a code you can switch on.

The errors

Code	Message	What to do
`DOCKER_UNAVAILABLE`	`Docker isn't running. Start it, then retry. (hone env doctor)`	Start Docker Desktop / the daemon.
`NO_FREE_PORTS`	`No free ports in {from}-{to}. Destroy a clone or widen the range.`	`destroy` an unused clone, or widen `portRange` in `config.json`.
`PORT_IN_USE`	`Port {port} is busy.`	Free the port or let the allocator pick another.
`CLONE_START_FAILED`	`{id} failed to start. See logs: hone env logs {id}`	Check `hone env logs <id>` for the underlying failure.
`HEALTH_TIMEOUT`	`{id} didn't become healthy in {seconds}s. See logs: hone env logs {id}`	The backend started but never passed its health check — inspect logs.
`SCHEMA_MISSING`	`{id} has no schema yet. Migrations will run before seeding.`	Informational — migrations run before the seed.
`SEED_VALIDATION`	`{rejected} generated record(s) were rejected by validation.`	Some AI records failed the clone’s validation; usually safe to ignore or re-seed.
`LLM_UNAVAILABLE`	`AI seeding is degraded. Retry with: hone env seed`	Check `ANTHROPIC_API_KEY` and connectivity, then retry.
`CONTROL_PLANE_DOWN`	`Control plane unreachable. Working locally, will sync later.`	Connected mode only — the CLI keeps working locally.
`DOCS_FETCH_FAILED`	`Couldn't fetch live {product} docs. Showing last known fidelity.`	`verify` only — live docs were unreachable; cached score shown.
`CLONE_NOT_FOUND`	`Unknown clone "{id}". List clones: hone env status`	Check the id with `hone env status`.
`TEMPLATE_NOT_FOUND`	`Unknown template "{template}". List templates: hone env ls --templates`	Check the template name.
`REGISTRY_CORRUPT`	`Local registry is corrupt. Rebuild it with: hone env doctor`	Run `hone env doctor` to recover.
`ENV_SPEC_INVALID`	`{what's wrong with the environment.yaml}`	`env spin` only — fix the spec: a typo’d key, a missing field, or a not-yet-supported section (`identity` or `data`). The message says exactly what.

Image & registry errors

Clone backends ship as published images that the CLI pulls (and verifies) at spin time. These cover everything that can go wrong fetching one.

Code	Message	What to do
`REGISTRY_UNREACHABLE`	`Can't reach the image registry for {image}. Check your network and retry.`	Network/DNS/TLS failure reaching the registry. A previously-cached image still runs.
`IMAGE_NOT_FOUND`	`Image "{image}" was not found. Check the tag, or run: hone env upgrade`	The tag doesn’t exist — check the ref, or `hone env upgrade` to repin.
`REGISTRY_AUTH`	`Access denied pulling "{image}". The package should be public — check the ref, or 'docker login'.`	The package is public, so this usually means a typo’d ref; otherwise `docker login`.
`IMAGE_PULL_FAILED`	`Couldn't pull "{image}". Retry, or check Docker has registry access.`	A pull failed for another reason (partial layer, daemon error) — retry.
`IMAGE_DIGEST_MISMATCH`	`The pinned image for this clone ({image}) is gone. Repin with: hone env upgrade`	The pinned digest was withdrawn (`:latest` re-tagged) — run `hone env upgrade` to repin.
`IMAGE_VERIFICATION_FAILED`	`Image "{image}" failed signature verification — refusing to run it.`	Fails closed — the image is unsigned or tampered; re-pull a genuine image.

Exit codes

Code	Meaning
`0`	Success.
`1`	A known `AsymmetricError` (one of the above), or a per-template failure during `spin`.
`2`	Bad invocation (e.g. `query` with no SQL, or `--json` + `--write`) or an unexpected error.

Design intent

The error map is part of the contract, not an afterthought. Each failure mode in the system has exactly one named error with a stable code and a userMessage, so the same failure reads the same way everywhere and tools can switch on the code. If you’re building a provider or a template, throw these — never a bare Error.

Get started

Concepts

Guides

Templates

Reference

CLI reference

Error reference

The errors

Image & registry errors

Exit codes

Design intent

​The errors

​Image & registry errors

​Exit codes

​Design intent

The errors

Image & registry errors

Exit codes

Design intent