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

# Error codes

> The durable E_* error-code table for the Extension.js schema-1 envelope, grouped by area, with the folded and legacy name mappings from codes.json.

Branch on a stable code, never on message text.

Every failure envelope carries one `E_*` code from a single table. Codes may be added, never renamed or removed. The message beside a code is free copy and may change in any release.

The table ships as `extension-develop/contract/codes.json`, see [Result envelope](/docs/contracts/result-envelope).

## Usage

| Code | Meaning |
| - | - |
| `E_ARGS` | A required argument is missing or the invocation is malformed. |
| `E_INVALID_OPTION` | A flag or argument value is not in the accepted set. |
| `E_FLAG_VALUE_INVALID` | A flag value failed validation. |
| `E_FLAG_NOT_SUPPORTED_HERE` | The flag exists but does not apply to this command or target. |
| `E_REMOVED_FLAG` | The flag was removed from the CLI. |
| `E_UNKNOWN_COMMAND` | No subcommand matches the given name. |
| `E_NODE_VERSION` | The running Node version is below the supported minimum. |
| `E_COMMAND_UNSUPPORTED_FOR_TARGET` | The command does not support the requested browser target. |
| `E_UNSUPPORTED_BROWSER` | The requested vendor is not in the supported browser list. |
| `E_BROWSER_NOT_INSTALLABLE` | The browser ships with the OS and cannot be installed by the CLI. |
| `E_PARENT_GONE` | The `--parent-pid` owner died, so the dev server self-terminated. |
| `E_REMOTE_URL_UNSUPPORTED` | The operation does not accept a remote URL. |

## Project

| Code | Meaning |
| - | - |
| `E_PROJECT_NOT_FOUND` | The resolved project folder does not exist. |
| `E_CONFIG_LOAD` | `extension.config.js` threw while loading, or exported something other than an object. `dev`, `build`, `start`, and `preview` all answer with it. |
| `E_MANAGED_DEP_CONFLICT` | The project declares a package that the toolchain manages. |
| `E_DEPENDENCY_INSTALL` | Installing project dependencies failed. |
| `E_TYPES_EMIT` | Writing `extension-env.d.ts` failed. |
| `E_TSCONFIG_MISSING` | TypeScript sources exist with no `tsconfig.json` beside `package.json`. |
| `E_OPTIONAL_DEP_UNRESOLVED` | An optional dependency contract could not be resolved. |
| `E_OPTIONAL_DEP_LOAD` | An optional dependency resolved but failed to load. |
| `E_OPTIONAL_DEP_UNKNOWN` | Unknown optional-dependency contract id. |
| `E_COMPANION_EXTENSION_PATH` | A companion extension path escapes `extensions/` or yielded nothing unpacked. |
| `E_MANIFEST_IN_PUBLIC` | `manifest.json` was placed under `public/`. |
| `E_RUNTIME_NOT_FOUND` | The extension-develop runtime is missing or uncompiled. |

## Manifest

| Code | Meaning |
| - | - |
| `E_MANIFEST_NOT_FOUND` | No `manifest.json` at the resolved root. |
| `E_MANIFEST_INVALID` | The manifest is not parseable JSON or not a WebExtension manifest. |

## Compile

| Code | Meaning |
| - | - |
| `E_FIRST_COMPILE` | The first compile of a session failed, so nothing was loaded. |
| `E_COMPILE` | A compile finished with errors. |
| `E_COMPILE_FATAL` | The compiler itself failed or returned unusable stats. |
| `E_MODULE_NOT_FOUND` | A module specifier could not be resolved. |
| `E_ENTRY_NOT_FOUND` | A manifest, HTML, or JSON entry points at a missing file. |
| `E_ASSET_MISSING` | An icon, static asset, or JSON dependency is missing. |
| `E_SCRIPT_DEP_MISSING` | A runtime script dependency could not be traced. |
| `E_RESERVED_FOLDER` | A reserved `scripts/` folder shape was violated. |
| `E_CSS_PARSE` | A stylesheet failed to parse. |
| `E_CSS_PREPROCESSOR_MISSING` | A CSS preprocessor is requested but not resolvable. |
| `E_CSS_DEAD_REF` | A CSS `url()` points at nothing. |
| `E_INTEGRATION_INSTALL` | A framework integration failed to install. |
| `E_POLYFILL_NOT_FOUND` | webextension-polyfill requested but absent. |
| `E_LOCALES_LAYOUT` | `_locales` layout or `messages.json` is invalid. |
| `E_WAR_INVALID` | `web_accessible_resources` shape or match pattern rejected. |
| `E_MATCH_PATTERN_INVALID` | The browser rejected a content-script match pattern. |
| `E_BACKGROUND_REQUIRED` | The reload runtime needs a background chunk that is absent. |
| `E_CONTENT_SCRIPT_SYNTAX` | A content script failed to parse. |
| `E_NO_ENTRYPOINTS` | The compilation produced zero entrypoints. |
| `E_REMOTE_RESOURCE_BLOCKED` | A remote script or stylesheet is blocked by extension CSP. |
| `E_PERF_BUDGET` | An asset exceeds its size budget. |
| `E_ZIP_SKIPPED` | Packaging was skipped for a stated reason. |
| `E_ENV_NO_MATCH` | No `.env` file matched the mode. |

`E_COMPILE` and `E_FIRST_COMPILE` are the top-level codes of a failed compile. Fifteen rows above travel inside that frame's `error.details`, one per diagnostic: `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`. The same codes open a successful build's `warnings` strings as an `E_CODE: ` prefix. See [Compile diagnostics](/docs/contracts/result-envelope).

## Remote projects and network

| Code | Meaning |
| - | - |
| `E_REMOTE_FETCH_TIMEOUT` | A remote fetch exceeded its timeout. |
| `E_REMOTE_DOWNLOAD` | A remote extension could not be downloaded or written to disk, for example a refused connection or an HTTP error. The message reads `Couldn't download the ZIP file or write it to disk.` |
| `E_REMOTE_ZIP_INVALID` | The remote URL did not return a ZIP, returned a damaged one that will not unpack, or returned one with an entry outside its folder. That last archive is refused before anything is written, and its message names the entry with no advice to try again. |
| `E_LOCAL_ZIP_NOT_FOUND` | A referenced local zip is missing or not a zip. |
| `E_PROJECT_DOWNLOAD_EMPTY` | Download succeeded but the extracted folder is absent. |
| `E_NETWORK` | A network request failed or timed out. |

## Browser binary and launch

| Code | Meaning |
| - | - |
| `E_BROWSER_NOT_FOUND` | No installed binary for the requested vendor. |
| `E_BROWSER_BINARY_REQUIRED` | A `-based` target needs an explicit binary path. |
| `E_BROWSER_BINARY_INVALID` | The pinned `--chromium-binary` or `--gecko-binary` does not exist, is not an executable file, or did not answer its version probe within 10 seconds. `start`, `dev`, and `preview` answer it with status `usage`. |
| `E_BROWSER_LAUNCH` | The browser process failed to spawn or died at startup. |
| `E_BROWSER_EXITED` | The launched browser exited while the server kept running. |
| `E_BROWSER_START_TIMEOUT` | The browser never signalled startup. |
| `E_PROFILE_LOCKED` | The profile directory is held by another browser process. |
| `E_LAUNCH_SKIPPED_COMPILE_ERRORS` | Launch was withheld because the compile failed. |
| `E_INSTANCE_AMBIGUOUS` | More than one live instance matches the requested id. |
| `E_WSL_INTEROP` | WSL interop could not resolve a Windows browser. |
| `E_BROWSER_DOWNLOAD` | Downloading or installing a browser failed. |
| `E_BROWSER_INSTALL_PRIVILEGE` | The install needs an interactive privileged session. |
| `E_BROWSER_UNINSTALL` | Removing an installed browser failed. |
| `E_UNINSTALL_NOOP` | Nothing to remove. |

## Browser runtime

| Code | Meaning |
| - | - |
| `E_EXTENSION_LOAD_REFUSED` | The browser refused the unpacked extension. |
| `E_ADDON_INSTALL` | Gecko temporary add-on install failed. |

## Debug protocol

| Code | Meaning |
| - | - |
| `E_BROWSER_CONNECT` | The debug connection could not be opened, for example a Firefox whose debugger never answers. |
| `E_BROWSER_CONNECTION_CLOSED` | The debug socket closed mid-session. |
| `E_CDP_NOT_CONNECTED` | An operation was issued with no live CDP transport. |
| `E_CDP_TIMEOUT` | A CDP command or load event timed out. |
| `E_CDP_OP_FAILED` | An extension operation over CDP failed. |
| `E_EXTENSION_ID_UNKNOWN` | The extension id could not be determined over CDP. |
| `E_RDP_PROTOCOL` | A malformed or unexpected RDP exchange. |

## Dev server

| Code | Meaning |
| - | - |
| `E_DEV_SERVER_START` | The dev server failed to start. |
| `E_PORT_IN_USE` | The requested port was taken and auto-reassigned. |
| `E_PORT_UNAVAILABLE` | No free port could be bound near the requested one. |

## Ready contract

| Code | Meaning |
| - | - |
| `E_SESSION_NOT_FOUND` | No live session contract for this project and browser. |
| `E_SESSION_STOPPED` | The session contract reports a stopped session. |
| `E_READY_TIMEOUT` | `--wait` expired before the session became ready. |
| `E_READY_ERROR_STATUS` | The ready contract reports an error for this session. |

## Control channel

| Code | Meaning |
| - | - |
| `E_CONTROL_UNAVAILABLE` | The control channel is absent, mismatched, or not answering. |
| `E_CONTROL_DENIED` | The session refused the control operation. |
| `E_TOKEN_MISSING` | The operation needs a session token that is not present. |
| `E_EVAL_REFUSED` | Eval is disabled for the session or the token does not match. |
| `E_TIMEOUT` | The operation did not answer inside its timeout. |
| `E_NOT_IMPLEMENTED` | The operation is not implemented for this context or engine. |
| `E_TARGET_NOT_FOUND` | No tab, frame, or context matched the requested target. |
| `E_HEADED_WINDOW_REQUIRED` | The surface needs a headed browser window that this session does not have. |
| `E_USER_GESTURE_REQUIRED` | The surface needs a real user gesture that the caller cannot synthesize. |
| `E_EVAL` | The evaluated expression threw inside the page. |
| `E_CSP_BLOCKS_EVAL` | A content security policy forbids eval in the target, so no expression runs there. |
| `E_INSPECT` | DOM inspection failed inside the guest. |
| `E_STORAGE` | `chrome.storage` rejected the read or write. |

## Logs

| Code | Meaning |
| - | - |
| `E_LOGS_NOT_FOUND` | No logs stream for this project and browser. |
| `E_LOGS_STREAM_GAP` | The follow stream dropped events. |

## Create

| Code | Meaning |
| - | - |
| `E_TEMPLATE_NOT_FOUND` | The template is not in the catalog or has no manifest. |
| `E_DESTINATION_NOT_EMPTY` | The destination already holds conflicting files. |
| `E_DESTINATION_NOT_WRITABLE` | The destination directory is not writable. |

## Everything else

| Code | Area | Meaning |
| - | - | - |
| `E_PREVIEW_NO_DIST` | preview | No unpacked extension at the resolved output path. |
| `E_SAFARI_TOOLCHAIN` | safari | The Safari toolchain is unavailable or an invocation failed. |
| `E_PUBLISH_REJECTED` | publish | The platform rejected the upload. |
| `E_AUTH_REQUIRED` | publish | The operation needs an auth token that is not present. |
| `E_TELEMETRY_WRITE` | telemetry | The telemetry consent file could not be written. |
| `E_DOCTOR_CHECKS_FAILED` | doctor | One or more doctor checks reported fail. |
| `E_INTERRUPTED` | internal | The operation was interrupted before it finished. |
| `E_INTERNAL` | internal | An unexpected fault reached the top-level sink. |

## Folded and legacy names

`codes.json` carries two extra mappings beside the table:

* `folded` maps finer inventory names onto a shipped family code. For example `E_ARG_REQUIRED` folds onto `E_ARGS`, and `E_BROWSER_NOT_INSTALLED` folds onto `E_BROWSER_NOT_FOUND`.
* `legacy` maps the three pre-envelope conventions onto the table. Snake\_case `ready.json` codes (`profile_locked` to `E_PROFILE_LOCKED`), PascalCase error names (`TargetNotFound` to `E_TARGET_NOT_FOUND`), and kebab-case doctor check ids (`eval-token` to `E_TOKEN_MISSING`).

If your consumer meets a name outside the table, resolve it through these mappings before branching.

## Next steps

* See where codes travel in the [Result envelope](/docs/contracts/result-envelope).
* Watch failure frames live in the [Lifecycle stream](/docs/contracts/lifecycle-stream).


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