Error codes

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.

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.
Watch failure frames live in the Lifecycle stream.

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Usage

Project

Manifest

Compile

Remote projects and network

Browser binary and launch

Browser runtime

Debug protocol

Dev server

Ready contract

Control channel

Logs

Create

Everything else

Folded and legacy names

Next steps

​Usage

​Project

​Manifest

​Compile

​Remote projects and network

​Browser binary and launch

​Browser runtime

​Debug protocol

​Dev server

​Ready contract

​Control channel

​Logs

​Create

​Everything else

​Folded and legacy names

​Next steps

Usage

Project

Manifest

Compile

Remote projects and network

Browser binary and launch

Browser runtime

Debug protocol

Dev server

Ready contract

Control channel

Logs

Create

Everything else

Folded and legacy names

Next steps