Skip to main content
Common errors, what causes them, and how to fix them. Each entry mirrors the CLI’s own error: … fix: … output.
Cause: your installed CLI predates the command. facet instructions, facet modify, headless facet create, and facet build --verify/--json require v0.24.0 or newer.Fix: update in place with facet self-update, then re-run:
Cause: facet search, a registry facet add, and facet publish need network access to the registry. Offline, they fail closed rather than write an unconfirmed entry.Fix: check your connection and retry. Note that local paths (./my-facet) and git sources (github:owner/repo) resolve without the registry, so you do not need registry access to install/add from these sources.
Cause: a facet has to be materialized into at least one adapter, but none is connected. In a real terminal facet add shows a picker; in a non-interactive shell (CI, piped stdin) it exits with an error instead.Fix: install an adapter first with facet adapter install:
Cause: facet publish (and facet whoami) need a registry credential and none was found.Fix: authenticate with facet login, then retry. In CI, prefer the FACET_TOKEN environment variable:
Cause: published (name, version) pairs are immutable — you can’t republish a version with different content. The status table lives at facet publish.Fix: bump the version, rebuild, and publish again:
Cause: skills is written as an array of strings. It must be a map of name → descriptor.Fix:
Then re-check with facet build --verify. See the Manifest reference.

​
Still stuck?

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