> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/docsfab/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/docsfab/_mcp/server.

# DocsFab Operator Error Envelope

> Look up the DocsFab operator error envelope schema and situation-class docs anchors.

DocsFab CLI, doctor, and init failures that reach the operator boundary
use one JSON object: schema version 1, kind `docsfab-operator-error`. The
machine identity is `code`. That value is the thrown `error.code` after
kebab-case sanitization. Agents consume `--json`. Do not scrape the human
lines. For more information, refer to [DocsFab Status and Configuration
Reference](/docsfab/reference/status-and-configuration).

This page documents that envelope schema. It is not a catalog of contract
stems, first-pass support rules, or doctor diagnostic codes. For the
class map of every operator-visible stop, refer to
[Stop Classes in DocsFab](/docsfab/reference/status-and-configuration/stop-classes).
For symptom-led recovery, refer to
[Troubleshooting DocsFab](/docsfab/troubleshooting).

## Identity Rules

The following rules are frozen for schema version 1:

- `kind` is always `docsfab-operator-error`.
- `schemaVersion` is `1`. There is no schema version 2 field on this
  envelope.
- `envelope.code` is `error.code` when that code is lowercase kebab-case.
  A code that fails the pattern becomes `operator-error`.
- Optional `nextAction`, `docsAnchor`, and `details` are derived at the
  operator boundary. They do not replace `code`.

Leaked contract stems such as `invalid-shape` remain valid `code` values
when a closed schema throws them. They are not troubleshooting situation
headings. Doctor diagnostics such as `project-config-missing` are a
separate closed family on
[Runtime Readiness and Doctor Checks in DocsFab](/docsfab/manage/check-readiness).

## Required Fields

`--json` always includes the following fields: `schemaVersion`, `kind`,
`code`, and `message`.

The following table lists the value of each required field.

| Field | Value |
| --- | --- |
| `schemaVersion` | `1` |
| `kind` | `docsfab-operator-error` |
| `code` | Lowercase kebab-case machine identity, copied from `error.code` |
| `message` | Credential-scrubbed operator sentence |

A representative identity-pass payload looks like this:

```json
{
  "schemaVersion": 1,
  "kind": "docsfab-operator-error",
  "code": "invalid-shape",
  "message": "External-input contract rejected: invalid-shape.",
  "nextAction": "Inspect the rejected artifact against the published contract schema, then retry with a conforming payload."
}
```

That example has no `docsAnchor` because `invalid-shape` is a contract
stem, not a situation-class docs target.

## Optional Fields

The serializer omits an optional field when it is empty. The following
table lists the optional fields.

The following table lists each optional field and when it appears.

| Field | When it appears |
| --- | --- |
| `nextAction` | A situation-class next action, inferred remediation, or throw-site action exists |
| `docsAnchor` | A repo-relative Markdown path is configured for that `code` or remediation |
| `failure` | Always written by current builds: the failure class, layer, and classified code |
| `details` | The throw is a recognized host failure type with content-free evidence |
| `originalRequestCompletion` | First-pass support projected `complete` or `incomplete` |
| `draftApplicability` | First-pass support projected a draft class |
| `documentationPartialLocator` | A host-held draft locator string is present |

`draftApplicability` is one of `useful-partial`, `scaffold-only`,
`no-useful-deliverable`, `cancellation`, or `execution-failure`.

`details.kind` is one of the following recognized evidence shapes:

- `docsfab-proposal-scope-admission-failure`
- `docsfab-first-pass-support-failure`
- `docsfab-first-pass-evidence-gap`
- `docsfab-repository-workspace-materialization-failure`

Those objects carry digests, phases, rules, counts, and limits. They do
not echo rejected target text, prompts, or credential values. First-pass
`rule` names stay inside `details`. They are not public situation ids.

## Failure Class

`failure` names why the command failed, as one value from a closed list,
so reports can count failures by cause. It has exactly the following three
fields.

| Field | Value |
| --- | --- |
| `class` | One failure class, such as `auth`, `operator-input`, or `model-content` |
| `layer` | `cli` for an operator-boundary refusal, or `inference` when a model attempt caused it |
| `code` | The catalogued code the class was read from |

Each situation catalog row carries its class, so `code` usually equals the
envelope `code`. A first-pass stop names its rule instead. An inference
failure names its coded rejection, or the provider error its attempt recorded,
such as `provider-http-auth` for an HTTP 401. When the model request layer
wrapped another error, the envelope names that error's own code, the same code
the failed run records. A refusal at a catalogued operational limit carries
that limit's `refusal` from `config/limits/` as its `code`, such as
`autonomy-authorization-window-ms-bound`, and its class is `bound`. Earlier
versions reported these refusals as `operator-error`. A code that no catalog row or table names
reads as `unknown` with that code, which shows what still needs a class. The class of a
failed installed quality pack follows the error type, not the code. That failure reads
`infrastructure` with any pack code, while other errors that reuse a pack code, such as
`unsafe-path` from a repository check, stay `unknown`. For
the full list of classes, refer to
[Failure Classes](/docsfab/reference/status-and-configuration/stop-classes#failure-classes).

A classified payload looks like this:

```json
{
  "schemaVersion": 1,
  "kind": "docsfab-operator-error",
  "code": "gitlab-unauthenticated",
  "message": "GitLab rejected the request for the selected host.",
  "nextAction": "Run `glab auth login --hostname <host from the selected remote>`; no SCM credential is stored by DocsFab.",
  "failure": { "class": "auth", "layer": "cli", "code": "gitlab-unauthenticated" }
}
```

## Human Lines and JSON

Human stderr (or the reporter's write callback) prints the message, then
these lines when the fields exist:

```text
code: <code>
failure class: <class> (layer <layer>)
Next action: <actionable sentence>
Docs: <repo-relative Markdown path>
```

The `failure class:` line adds `, code <code>` inside the parentheses when
the classified code differs from `code:`. `--json` always includes `code`.
Additional `Evidence:`, original-request, draft-applicability, and
host-held draft locator lines appear only when the matching optional
fields are present.

`Docs:` stays a repository-relative path such as
`docs/troubleshooting.md`. When Fern publishes that
file, the site route is the path under `docs/` without the `docs/` prefix
or `.md` suffix, for example
[Troubleshooting DocsFab](/troubleshooting). Printed
operator output does not substitute that URL for the `Docs:` line.

## Credential Scrub

Every operator string is scrubbed before it leaves the envelope. The
boundary redacts credential-shaped tokens, HTTP and HTTPS URLs, and host
paths under `Users`, `home`, or `root`. Replacements are `[REDACTED]`.
JSON pointers such as `$.packet` remain visible. Origin-only HTTPS URLs
that match an installed executable route remain visible so a
`deployment-binding-mismatch` refusal can name the recorded origin. URLs
with a path, query, fragment, username, or password still redact,
including those same hosts.

## Situation-Class Docs Anchors

Situation-class recovery headings are the `DEFAULT_DOCS_ANCHORS` keys
that already have a docs path, plus doctor diagnostics as a separate
family. They are not the full next-action map and not the contract-stem
set.

Each of the following pages names the `code` it documents. Each code whose
`Docs:` path is `docs/troubleshooting.md` has a row in the
[Error Messages](/docsfab/troubleshooting#error-messages) table on that page. The following table
maps each situation-class `code` to its docs path and published page.

The following table lists each snapshotted code, its `Docs:` path, and its published Fern page.

| `code` | `Docs:` path | Published Fern page |
| --- | --- | --- |
| `migration-required` | `docs/about/architecture.md` | [DocsFab Architecture](/about/architecture) |
| `cli-usage` | `docs/reference/status-and-configuration/human-output-and-json.md` | [Human Output and JSON](/reference/status-and-configuration/human-output-and-json) |
| `doctor` | `docs/manage/check-readiness.md` | [Check Readiness](/manage/check-readiness) |
| `profile-inspect` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `profile-inspection-clock-invalid` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `profile-evidence-invalid` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `invalid-model-profile-configuration` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `unsupported-model-profile-api-format` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `invalid-model-profile-approval` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `profile-apply-rejected` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `profile-owner-artifact-rejected` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `profile-apply-ambiguous` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `profile-rollback-ambiguous` | `docs/reference/status-and-configuration/model-profile-approval.md` | [Model-Profile Approval](/reference/status-and-configuration/model-profile-approval) |
| `glab-auth-login` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `aggregate-timeout` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `per-blob-timeout` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `source-authority-path-refused` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `composition-retired` | `docs/configure/model.md` | [Configure the Model](/configure/model) |
| `setup-model-choice-required` | `docs/configure/model.md` | [Configure the Model](/configure/model) |
| `profile-seed-choice-required` | `docs/reference/status-and-configuration/model-profile-fields.md` | [Model-Profile Fields](/reference/status-and-configuration/model-profile-fields) |
| `deployment-binding-mismatch` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `model-endpoint-insecure-transport` | `docs/configure/model.md` | [Configure the Model](/configure/model) |
| `tracked-source-dirty` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `not-a-git-repository` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `not-repository-root` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `unsafe-git-configuration` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `git-identity-drift` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `git-configuration-refused` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `git-checkout-unverified` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `ambiguous-remote` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `repository-mismatch` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `first-pass-support-invalid` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `required-source-unread` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `preflight-budget-exceeded` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `content-index-refused` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `content-index-unreadable` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `context-compile-failed` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `navigation-alias-refused` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `empty-page-anchor` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |
| `duplicate-page-anchor` | `docs/troubleshooting.md` | [Troubleshooting DocsFab](/troubleshooting) |

A missing-profile `migration-required` throw can override that stem's
architecture page and send `Docs:` to
[Install DocsFab](/docsfab/get-started/installation) through the
`profile-seed` remediation.

## Related Topics

For more information, refer to the following pages:

- [Runtime CLI and Configuration in DocsFab](/docsfab/reference/status-and-configuration/runtime-cli-and-configuration)
- [Runtime Readiness and Doctor Checks in DocsFab](/docsfab/manage/check-readiness)
- [Troubleshooting DocsFab](/docsfab/troubleshooting)
- [DocsFab Implementation Status](/docsfab/reference/status-and-configuration/implementation-status)