> ## 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. | | `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. | | `E_MANIFEST_SHAPE` | A manifest field has the wrong shape. | | `E_MANIFEST_PAGE_MISSING` | A manifest-referenced HTML page does not exist. | | `E_MANIFEST_VERSION_UNSUPPORTED` | The `manifest_version` is not supported on this target. | | `E_MANIFEST_LOAD_BLOCKERS` | Manifest fields that the browser will reject at load time. | | `E_MANIFEST_PERMISSION_MISSING` | A required permission is absent from the manifest. | | `E_MANIFEST_MSG_KEY_MISSING` | A `__MSG_x__` key is absent from the default locale. | | `E_MANIFEST_EMIT` | Manifest emit or persist failed. | | `E_RESTART_REQUIRED` | An entrypoint field changed and the dev server must restart. | ## 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. | ## Remote projects and network | Code | Meaning | | -------------------------- | ------------------------------------------------------ | | `E_REMOTE_FETCH_TIMEOUT` | A remote fetch exceeded its timeout. | | `E_REMOTE_DOWNLOAD` | Download or extraction of a remote extension failed. | | `E_REMOTE_ZIP_INVALID` | The remote URL did not return a zip. | | `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 given binary path does not exist or is not executable. | | `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. | | `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_DEV_SERVER_TIMEOUT` | Dev server start exceeded its timeout. | | `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_EXISTS` | A live session already exists 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_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. | | `E_CREATE_DIR` | The target directory could not be created. | | `E_CREATE_WRITE` | A scaffold file could not be written. | | `E_CREATE_TESTS_SETUP` | Built-in test setup failed. | | `E_GIT_SKIPPED` | `git init` was skipped because git is absent. | ## 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).