> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<AccordionGroup>
  <Accordion title="&#x22;Unknown command&#x22; (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`](/cli/self-update), then re-run:

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    facet self-update
    facet --version
    ```
  </Accordion>

  <Accordion title="&#x22;could not reach the registry&#x22;">
    **Cause:** `facet search`, a registry `facet add`, and `facet publish` need network access to the registry. Offline, they [**fail closed**](/specification/commit#verify) 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.
  </Accordion>

  <Accordion title="&#x22;no adapters installed&#x22; 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`](/cli/adapters/install):

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    facet adapter install claude-code
    facet adapter list
    ```
  </Accordion>

  <Accordion title="&#x22;adapter incompatible&#x22; / &#x22;unsupported adapter API&#x22; (build, add, remove, install fail before writing)">
    **Cause:** every installed adapter declares the adapter API contract it was built against, and each CLI release supports an exact set (currently `0.1`, the tagged request/result contract). A bundle installed before API versioning has **no** declaration; a bundle built against the earlier positional contract declares `0.0`, which a `0.1` CLI treats as unsupported; other bundles can carry a malformed declaration, declare an API this CLI doesn't support, or disagree with the npm metadata they were selected by. All these cases fail closed: `facet build`, `facet add`, `facet remove`, and `facet install` stop **before** invoking any adapter method or writing project files.

    **Fix:** list your installed adapters to see each one's declared API and status, then run the reinstall command printed next to the incompatible entry:

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    facet adapter list
    # my-adapter  api missing  unsupported — reinstall: facet adapter install my-adapter
    facet adapter install my-adapter
    ```

    Reinstalling selects the newest release compatible with this CLI. See [compatible resolution](/cli/adapters/install#compatible-resolution) for how selection works, and note that [`facet adapter remove`](/cli/adapters/remove) always works regardless of compatibility.
  </Accordion>

  <Accordion title="&#x22;unsupported archive format&#x22; on install">
    **Cause:** the facet's archive uses a [`facetVersion`](/specification/archive) your CLI doesn't support. A newer facet may use a format published after your CLI; a corrupt or unknown archive fails the same way. The adapter API, archive `facetVersion`, and lockfile version are [independent axes](/specification/install) — this is the archive axis.

    **Fix:** update the CLI with [`facet self-update`](/cli/self-update). The error names the minimum supporting release when the format is known; when it isn't, update to the latest.
  </Accordion>

  <Accordion title="&#x22;integrity mismatch&#x22; / companion drift on install">
    **Cause:** a materialized file no longer matches the [per-file integrity](/specification/lockfile) recorded in `facets.lock` — a file was edited or corrupted on disk, or the cache was tampered with. Install reconciles every file (including each skill companion) before writing and reports the exact drifting path.

    **Fix:** re-run [`facet install`](/cli/install) — it repairs a drifted file in place (reported as *repaired*) without touching files you added yourself. If a registry facet fails to reconcile against its lockfile integrity, the download is rejected rather than silently replaced; confirm the lockfile matches what you expect.
  </Accordion>

  <Accordion title="&#x22;not signed in — no registry credential found&#x22;">
    **Cause:** `facet publish` (and `facet whoami`) need a registry credential and none was found.

    **Fix:** authenticate with [`facet login`](/cli/login), then retry. In CI, prefer the [`FACET_TOKEN`](/cli/env) environment variable:

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    facet login              # interactive
    export FACET_TOKEN=fct_pub_…   # or, for CI/scripts
    facet whoami             # confirm the identity
    ```
  </Accordion>

  <Accordion title="Publish rejected: version already exists (HTTP 409)">
    **Cause:** published `(name, version)` pairs are [**immutable**](/specification/publish#immutability) — you can't republish a version with different content. The status table lives at [`facet publish`](/cli/authoring/publish#publish-outcomes).

    **Fix:** bump the version, rebuild, and publish again:

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    facet modify facet --version 1.2.0
    facet build
    facet publish
    ```
  </Accordion>

  <Accordion title="Build fails: skills[&#x22;0&#x22;] must be an object">
    **Cause:** `skills` is written as an array of strings. It must be a **map** of name → descriptor.

    **Fix:**

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "skills": {
        "code-review": { "description": "Guidelines for reviewing code changes" }
      }
    }
    ```

    Then re-check with `facet build --verify`. See the [Manifest reference](/specification/manifest).
  </Accordion>
</AccordionGroup>

## Still stuck?

Ask in the [community Discord](https://discord.gg/qXQYaYna5w) or open an issue on [GitHub](https://github.com/agent-facets/facets).