Troubleshooting

Fix common facet CLI errors

Common errors, what causes them, and how to fix them. Each entry mirrors the CLI’s own error: … fix: … output.

"Unknown command" (e.g. facet instructions / modify)

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:

facet self-update
facet --version

"could not reach the registry"

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.

"no adapters installed" when running facet add (non-interactive)

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:

facet adapter install claude-code
facet adapter list

"not signed in — no registry credential found"

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:

facet login              # interactive
export FACET_TOKEN=fct_pub_…   # or, for CI/scripts
facet whoami             # confirm the identity

Publish rejected: version already exists (HTTP 409)

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:

facet modify facet --version 1.2.0
facet build
facet publish

Build fails: skills["0"] must be an object

Cause: skills is written as an array of strings. It must be a map of name → descriptor.

Fix:

{
  "skills": {
    "code-review": { "description": "Guidelines for reviewing code changes" }
  }
}

Then re-check with facet build --verify. See the Manifest reference.

Still stuck?

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