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

# Result envelope (schema 1)

> The schema-1 JSON envelope that every Extension.js command prints under --output json, plus the published schema, code table, and golden fixtures.

Parse one JSON document per command instead of scraping log lines.

Under `--output json`, every terminating command answers with exactly one schema-1 envelope on stdout. Long-running commands stream the same shape as [lifecycle frames](/docs/contracts/lifecycle-stream).

## Envelope shape

| Field | Type | Meaning |
| - | - | - |
| `schema` | `1` | The envelope version. Additive changes keep this number. |
| `ok` | boolean | Whether the command succeeded. |
| `command` | string | The command that produced this result. |
| `status` | string | A short machine status, for example `ready`, `usage`, or `failed`. |
| `value` | any or null | The command's payload. A failure can still carry one, `doctor` is the motivating case. |
| `error` | object or null | Present when `ok` is false, see below. |
| `warnings` | string\[] | Non-fatal notices. |
| `truncated` | boolean | Optional. Set when a payload was cut to fit a size cap. |
| `hint` | string | Optional. A next-step suggestion. |

The `error` object:

| Field | Type | Meaning |
| - | - | - |
| `code` | string | A stable `E_*` identifier from the [error code table](/docs/contracts/error-codes). Match on this. |
| `message` | string | Free copy that may be rewritten at any time. Plain text with no glyph and no color codes. Never match on it. |
| `name` | string | Optional. The originating error class name. |
| `engine` | string | Optional. The browser engine where the failure happened. |
| `hint` | string | Optional. Remediation copy. |
| `refs` | object | Optional. The actionable parts that the message names: `flag`, `command`, `path`, `version`. |
| `details` | array | Optional. Present on a failed compile. One entry per compiler diagnostic, see Compile diagnostics below. |

## Success and failure examples

```json theme={null}
{
  "schema": 1,
  "ok": true,
  "command": "capabilities",
  "status": "ok",
  "value": {
    "name": "extension",
    "version": "4.1.3",
    "envelopeSchema": 1,
    "readySchemaVersion": 2,
    "outputJsonCommands": [
      "build",
      "capabilities",
      "create",
      "dev",
      "doctor",
      "eval",
      "inspect",
      "install",
      "logs",
      "open",
      "preview",
      "publish",
      "reload",
      "start",
      "storage",
      "telemetry",
      "uninstall"
    ]
  },
  "error": null,
  "warnings": []
}
```

```json theme={null}
{
  "schema": 1,
  "ok": false,
  "command": "eval",
  "status": "failed",
  "value": null,
  "error": {
    "code": "E_TARGET_NOT_FOUND",
    "message": "No tab matched the requested target.",
    "hint": "List targets with `extension inspect --list-tabs`."
  },
  "warnings": []
}
```

## Compile diagnostics

A failed `build` frame and the dev stream's `compile-failed` frame carry `error.details`, one entry per compiler diagnostic, errors first. Each entry has this shape:

| Field | Type | Meaning |
| - | - | - |
| `code` | string | Optional. The table code the diagnostic resolves to, for example `E_MODULE_NOT_FOUND`. Absent when none does. |
| `message` | string | The compiler text, ANSI-stripped. Free copy, never match on it. |
| `file` | string | Optional. The source file, relative to the project root. |
| `line` | integer | Optional. The line in that file when the compiler reports one. |
| `column` | integer | Optional. The column on that line when the compiler reports one. |
| `severity` | `"error"` or `"warning"` | Which kind of diagnostic this is. |
| `name` | string | Optional. The compiler's error class name. |

The list is capped at 20 entries. When the cap cuts it, the frame sets `truncated: true`.

The codes that can appear in `details` are the diagnostic rows of the [error code table](/docs/contracts/error-codes): `E_MODULE_NOT_FOUND`, `E_CONTENT_SCRIPT_SYNTAX`, `E_CSS_PARSE`, `E_ENTRY_NOT_FOUND`, `E_ASSET_MISSING`, `E_SCRIPT_DEP_MISSING`, `E_RESERVED_FOLDER`, `E_CSS_PREPROCESSOR_MISSING`, `E_CSS_DEAD_REF`, `E_LOCALES_LAYOUT`, `E_WAR_INVALID`, `E_BACKGROUND_REQUIRED`, `E_REMOTE_RESOURCE_BLOCKED`, `E_PERF_BUDGET`, and `E_ENV_NO_MATCH`.

This is `golden.build.compile.json` with its two messages shortened to their first line:

```json theme={null}
{
  "schema": 1,
  "ok": false,
  "command": "build",
  "status": "build-failed",
  "value": null,
  "error": {
    "code": "E_COMPILE",
    "message": "Build failed with errors",
    "details": [
      {
        "code": "E_CONTENT_SCRIPT_SYNTAX",
        "message": "Module build failed (from builtin:swc-loader): Syntax Error: Expression expected",
        "file": "content/scripts.js",
        "severity": "error",
        "name": "ModuleBuildError"
      },
      {
        "code": "E_MODULE_NOT_FOUND",
        "message": "Module not found: Can't resolve './missing' in '/home/dev/my-extension'",
        "file": "background.js",
        "line": 1,
        "column": 1,
        "severity": "error"
      }
    ]
  },
  "warnings": [],
  "hint": "Fix the error above and run build again."
}
```

A successful build keeps its warnings in the top-level `warnings` array. Each string there opens with `E_CODE: ` when a code resolves, for example `E_CSS_DEAD_REF: ...`, the same convention `logs` and `uninstall` already use.

## Where human copy goes

The `EXTENSION_OUTPUT` environment variable is the machine-mode switch. When it is `json` or `ndjson`, frames own stdout and human copy moves aside:

* Informational lines and warnings go quiet, or move to stderr where a stream needs them.
* Error copy is never suppressed. It always writes to stderr, so a launch failure stays visible while stdout stays parseable.

Pipe stdout to your parser and keep stderr for humans. The two never mix.

## Published contract artifacts

The `extension-develop` package ships the contract as importable files under the `./contract/*` export:

| Artifact | What it is |
| - | - |
| `extension-develop/contract/envelope.schema.json` | JSON Schema for the envelope. Its `$id` is `https://extension.js.org/contract/envelope-1.json`. |
| `extension-develop/contract/codes.json` | The durable error-code table with `folded` and `legacy` mappings. |
| `extension-develop/contract/golden.*.json` | Golden fixtures, one per command and status, for example `golden.dev.ready.json` and `golden.eval.target-not-found.json`. |

Validate your consumer against the schema, and pin your tests to the golden fixtures. Codes may be added, never renamed or removed.

## Next steps

* Branch on failures with the [error code table](/docs/contracts/error-codes).
* Follow long-running sessions with the [lifecycle stream](/docs/contracts/lifecycle-stream).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.