Skip to main content
Errors that several commands can produce, with their cause and fix. An error only one command can produce lives on that command’s page, listed at the bottom of this page.

​
Cross-command errors

Cause: your CLI predates the command. facet instructions, facet modify, headless facet create, and facet build --verify need v0.24.0 or newer. facet update needs v0.33.0 or newer.Fix:
Cause: the command needs the registry and could not reach it. That covers facet search, a registry facet add, facet install, facet update, facet publish, and identity checks such as facet whoami. Offline, they fail rather than record something unverified.Fix: check your connection and retry. Local paths and git sources resolve without the registry.facet adapter add reports npm separately, because adapters resolve through the npm registry rather than the facet registry.
Cause: the manifest was written by a newer CLI. Versions match exactly, never by ordering. The current version is 0.2, and 0.1 or unversioned manifests still read and migrate on a successful install. Every command that reads the manifest fails the same way, including install, add, remove, list, and update.Fix: run facet self-update.A servers group inside a 0.1 document is a validation failure instead: run one non-frozen facet install to migrate first.
Cause: an installed adapter declares an API this CLI does not support, so every command that touches adapters fails closed, including build, add, install, remove, and update.Fix: list the adapters and run the reinstall command printed beside each flagged entry. See facet adapter list.
Cause: two facets would materialize under one name. Any command that installs can hit it, and nothing is written when it does.Fix: in a terminal, resolve it at the prompt. In CI, apply the printed facets.json edit. See name collisions.
Cause: a facet declares MCP servers this machine has not approved, and the run cannot prompt. Approval is machine-local, so a teammate’s approval does not cover yours. Nothing was written.Fix: pass --accept-mcp, or omit the servers you do not want. See MCP servers.
Cause: an install-pipeline command failed and rolled back, but at least one file could not be restored. Any of add, install, remove, and update can report this, and it outranks whatever error stopped the run.The report names each file with one of three outcomes:
  • changed by something else, left as it is: another editor or command wrote the file after this run did, so rollback declined to overwrite that work. Nothing is wrong with your file.
  • could not be read, left as it is: the file could not be inspected, so it was not touched.
  • could not be restored: the restore itself failed, usually permissions or disk.
No file is ever reported as both restored and unrecoverable, and you are never asked to choose between two versions of a contested file.Fix: for a preserved edit, decide whether you still want the change and re-run when you do. For a restore failure, resolve the named cause and re-run. Installing reconciles each file against its recorded integrity and repairs what it owns.

​
Command-specific errors

​
Still stuck?

Ask in the community Discord or open an issue on GitHub.