E_* code from a single table. Codes may be added, never renamed or removed, apart from the one move to W_* below. The message beside a code is free copy and may change in any release.
From the release after 4.1.41, a warning carries a W_* code: the run carried on past it. Errors and refusals keep their E_* code. See Warning codes.
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. From the release after 4.2.0, extension --output json with no command answers it as one usage frame. |
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. A commands.<cmd>.browser value in extension.config.js is checked the same way. From 4.2.0, an empty --browser value, or an empty item in a comma list, answers it too. |
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_PACKAGE_JSON_INVALID | From the release after 4.2.0. The project’s package.json cannot be opened, is not parseable JSON, opens with a byte order mark, or is saved as UTF-16. dev, build, start, and preview all answer with it before they compile. The message names the file. A file that cannot be opened ends with “Make it a file this user can read, then run the command again.” A parse error ends with “Fix the file, then run the command again.” An encoding ends with “Save the file as UTF-8 without a byte order mark, then run the command again.” extension doctor fails its peer-rspack check for the same file and says that no dependency was checked. From the release after 4.2.0, it also stops these commands when package.json is a folder or a special file and not a file. That message names the path and what it found there. |
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. A production build also answers with it for an invalid perfBudgets value, and from 4.2.0 so does dev. From the release after 4.2.0, a vue.loader or svelte.loader options file that throws stops the build with it too. |
E_DEPENDENCY_INSTALL | Installing project dependencies failed. |
E_OPTIONAL_DEP_UNRESOLVED | An optional dependency contract could not be resolved. |
E_OPTIONAL_DEP_LOAD | An optional dependency resolved but failed to load. From the release after 4.1.41, a copy in your project that throws on load stops the run. The message names its path and the cause. No other install stands in for it. |
E_OPTIONAL_DEP_UNKNOWN | Unknown optional-dependency contract id. |
E_COMPANION_EXTENSION_PATH | The only manifest at the resolved root belongs to a companion under extensions/. A companion entry that the browser opens without warns with W_COMPANION_EXTENSION_PATH. |
E_PROJECT_LAYOUT | A file in public/ would overwrite a file the build emits, or an include entry in extension.config.js names a missing file or an output path outside the extension. |
E_MANIFEST_IN_PUBLIC | manifest.json was placed under public/. |
E_FOLDER_UNREADABLE | A folder inside pages/ or scripts/ cannot be read, so the build cannot list its entries. From the release after 4.2.0. |
E_ENV_FILE_UNREADABLE | An env file that the build reads is a folder or cannot be read. From 4.2.0. |
E_RUNTIME_NOT_FOUND | The extension-develop runtime is missing, uncompiled, or at another version than the CLI. From the release after 4.2.0, it also covers an installed engine that throws while it loads, such as one whose native binding the install left out. The message names the engine folder, the reason, and the command that installs it again. |
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. From the release after 4.1.41, it also covers a plugin that throws while the compiler is made, such as in its apply. |
E_MODULE_NOT_FOUND | A module specifier could not be resolved. |
E_ENTRY_NOT_FOUND | A manifest, HTML, or JSON entry points at a file that is missing or not bundled. |
E_ASSET_MISSING | An icon, static asset, or JSON dependency is missing or not bundled. |
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() or @import names a file that is missing or not bundled. |
E_LOCALES_LAYOUT | _locales layout or messages.json is invalid. |
E_WAR_INVALID | web_accessible_resources shape or match pattern rejected. |
E_BACKGROUND_REQUIRED | Reserved from the release after 4.2.0 and no longer emitted. A missing background script reports E_ENTRY_NOT_FOUND in dev and in production builds. Up to 4.2.0, the reload runtime raised it when a background chunk was absent. |
E_CONTENT_SCRIPT_SYNTAX | A content script failed to parse. |
E_INLINE_SCRIPT_SYNTAX | From the release after 4.2.0. An inline script of an HTML file no longer parses once an unquoted placeholder is filled with its env value. |
E_PERF_BUDGET | An asset exceeds its size budget, and perfBudgets.onExceed is 'error', so the build fails. Without that setting the overrun warns with W_PERF_BUDGET. See Performance budgets. |
E_THEME_INVALID | A theme color or tint is not a number array a Chromium browser loads, and the build cannot translate it exactly. |
E_DEV_SESSION_DIST_SHARED | A build would write the output folder that a running dev session serves, so it was refused. Pass --out-dir to build beside it. |
E_OUTPUT_NOT_WRITABLE | The build could not write into the output folder: the folder is not writable, or manifest.json could not be written into it. From the release after 4.2.0, a read-only output folder answers it at build time too. The message names the folder and the reason (EACCES, EPERM, or EROFS), and asks you to make the folder writable or pick another with --out-dir. |
E_JSON_INVALID | A JSON file the manifest names does not parse, or its declarativeNetRequest ruleset or managed storage schema has a shape the browser rejects. |
E_ASSET_IMPORT_SHAPE | An asset imported with import * as is read as the file’s value, which is the default export. |
E_ZIP_SKIPPED | Packaging was skipped for a stated reason. |
E_COMPILE and E_FIRST_COMPILE are the top-level codes of a failed compile. Thirteen rows above travel inside that frame’s error.details, one per error: E_MODULE_NOT_FOUND, E_CONTENT_SCRIPT_SYNTAX, E_INLINE_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, and E_PERF_BUDGET. Up to 4.2.0, E_BACKGROUND_REQUIRED could appear there too. A warning in details has severity: "warning" and a W_* code. A successful build’s warnings strings open with the same W_CODE: prefix. See Compile diagnostics.
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_ACCESS_DENIED | The server answered the remote URL with a 401 or a 403. The link’s access token has expired, was revoked, or was changed while copying. The message names the expiry when the token carries one, and never prints the token. |
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. From the release after 4.1.39, a binary variable such as FIREFOX_BINARY that names a missing or non-executable path fails the same way. 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_INSTANCE_AMBIGUOUS | More than one live instance matches the requested id. |
E_BROWSER_DOWNLOAD | Downloading or installing a browser failed. From the release after 4.1.41, a missing package runner answers E_BROWSER_INSTALLER_NOT_FOUND instead. From the release after 4.2.0, it also covers a package runner that is there but does not start, and an install fault of no known kind answers E_INTERNAL instead. |
E_BROWSER_INSTALL_PRIVILEGE | The install needs an interactive privileged session. |
E_BROWSER_UNINSTALL | Removing an installed browser failed. |
E_BROWSER_INSTALL_TIMEOUT | The browser installer was still running at the install timeout and was stopped. |
E_BROWSER_INSTALL_BUSY | Another install of the same browser was still running after the whole wait, so this one never started. |
E_BROWSER_CACHE_NOT_WRITABLE | The browser cache root is a file, cannot be created, or cannot be written to. |
E_BROWSER_FOLDER_FOREIGN | The browser folder in the cache holds files the installers never write, so the install left it untouched. |
E_BROWSER_INSTALLER_NOT_FOUND | The package runner that installs the browser is not on this machine. |
Browser runtime
| Code | Meaning |
|---|---|
E_EXTENSION_LOAD_REFUSED | The browser refused the unpacked extension. From the release after 4.1.41, start, preview, dev --wait, start --wait, the act commands, and the dev --output json stream answer it with status load-refused and exit code 1. doctor --output json carries it with status unhealthy. |
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. |
W_CDP_NOT_CONNECTED, W_CDP_TIMEOUT, W_CDP_OP_FAILED, W_BROWSER_CONNECTION_CLOSED, or W_EXTENSION_ID_UNKNOWN. That covers ready.json cdpFaultCode too.
Dev server
| Code | Meaning |
|---|---|
E_DEV_SERVER_START | The dev server failed to start. |
E_PORT_UNAVAILABLE | No free port could be bound near the requested one. |
E_SESSION_EXISTS | A live dev session already owns this project and browser, so the new session was refused. |
E_RESTART_REQUIRED | A file the running dev session depends on was removed or changed in a way it cannot apply, so the session must be restarted. |
E_SHUTDOWN_TIMEOUT | From the release after 4.1.41. A dev session did not stop within its 10 second bound, so the process exited with code 1. |
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. From the release after 4.1.41, a run that ended on a refusal answers E_EXTENSION_LOAD_REFUSED at once, unless the manifest changed after the refusal. |
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. |
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_SAFARI_UI | safari | A read or action on Safari’s own settings or toolbar failed. |
E_ACCESSIBILITY_DENIED | safari | macOS has not granted the host app Accessibility, so Safari’s own UI cannot be read or driven. |
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. |
Warning codes
From the release after 4.1.41, every coded warning carries aW_* code. It shows on an error.details entry with severity: "warning", at the start of each warnings string, and in ready.json cdpFaultCode. A class that can fail and warn has one code under each prefix with the same stem, such as E_PERF_BUDGET and W_PERF_BUDGET.
Releases up to 4.1.41 reported many of these warnings under the E_* name with the same stem, such as E_CSS_DEAD_REF. A script that matches a warning by code reads W_ in place of E_. No alias exists.
| Code | Meaning |
|---|---|
W_MANAGED_DEP_CONFLICT | The project declares a package the toolchain manages. |
W_TYPES_EMIT | Writing extension-env.d.ts failed. |
W_MODULE_NOT_FOUND | A module specifier could not be resolved, and the build carried on without it. |
W_ENTRY_NOT_FOUND | A manifest, HTML, or JSON entry points at a file that is missing or not bundled. |
W_ASSET_MISSING | An icon, static asset, or JSON dependency is missing or not bundled. |
W_SCRIPT_DEP_MISSING | A file a script loads at runtime is missing from the build, is named by its source spelling, or could not be compiled. From the release after 4.2.0, a new URL("...", import.meta.url) reference in a script that names no file beside it and no installed package reports it too. The build keeps the address as written, and EXTENSION_STRICT_REFS=true turns it into E_SCRIPT_DEP_MISSING. |
W_CSS_PARSE | A stylesheet failed to parse, or the minifier dropped a rule and the sheet ships as authored. |
W_CSS_PREPROCESSOR_MISSING | A CSS preprocessor is requested but not resolvable. |
W_CSS_DEAD_REF | A CSS url() or @import names a file that is missing or not bundled. |
W_POLYFILL_NOT_FOUND | webextension-polyfill requested but absent. From the release after 4.2.0, it is listed among the first compile’s warnings, where every output format reads them. |
W_LOCALES_LAYOUT | _locales layout or messages.json is invalid. |
W_PROD_LOOPBACK_ORIGIN | A production manifest names a loopback origin (localhost, 127.0.0.0/8, [::1], or 0.0.0.0), which store reviewers read as unexplained host access. |
W_NO_ENTRYPOINTS | The compilation produced zero entrypoints. |
W_REMOTE_RESOURCE_BLOCKED | A remote script or stylesheet is blocked by extension CSP. |
W_PERF_BUDGET | An asset exceeds its size budget. |
W_ENV_NO_MATCH | No .env file matched the mode. |
W_LAUNCH_SKIPPED_COMPILE_ERRORS | Launch was withheld because the compile failed. |
W_UNINSTALL_NOOP | Nothing to remove. |
W_PORT_IN_USE | The requested port was taken and auto-reassigned. |
W_LOGS_STREAM_GAP | The follow stream dropped events. |
W_MANIFEST_INVALID | A manifest field had a shape the browser refuses to load, and the build repaired or dropped it. |
W_WAR_INVALID | A web_accessible_resources pattern leaves the extension root, so it exposes no file. From the release after 4.2.0, it also marks a listed stylesheet whose url() targets the build does not ship. |
W_RESERVED_FOLDER | A file in scripts/ is only imported by another file, and every file in that folder is built as an entry of its own. |
W_INTERNAL | A build step met output it did not expect and carried on. The toolchain needs an update. |
W_RESTART_REQUIRED | A file the running dev session reads only at startup changed, so the change applies after a restart. |
W_RELOAD_NOT_APPLIED | From the release after 4.2.0, printed in the browser console of a dev session: a reload or hot update could not be applied there, so the open page or extension keeps the build it has. |
W_CONTENT_SCRIPT_NOT_INJECTED | From the release after 4.2.0, printed in the background console of a dev session: the background could not answer a page that asks for its content script, so that page runs without it. |
W_DEV_SERVER_SOCKET | From the release after 4.2.0, printed in the console of an extension page in a dev session: the socket to the dev server failed, so edits show after the page is reloaded. |
W_CONTENT_SCRIPT_CLEANUP | From the release after 4.2.0, printed in the page console: the cleanup function that a content script returned threw, so what the script left on the page may stay. |
W_CONTENT_SCRIPT_MOUNT | From the release after 4.2.0, printed in the page console: the default export of a content script threw when it ran. |
W_JSON_INVALID | A declarativeNetRequest ruleset parses but has a rule that may not behave as written, or one that Chrome refuses and Firefox loads. |
W_PROJECT_LAYOUT | A public/ folder is misplaced or shadowed by another one, or an exclude entry in extension.config.js names a file that is not there. From the release after 4.2.0, it also covers a public/ folder named in another letter case and a public/ file shadowed by an entry. It also covers a Pages/ or Scripts/ folder, which no build reads, and two files in pages/ or scripts/ that build under one entry name. |
W_MANIFEST_COMPAT | The manifest uses a version, key, or host permission pattern that the target browser ignores or is phasing out. From the release after 4.2.0, it also marks a browser prefix on a permission item, which the build resolves for each browser. |
W_STORE_READINESS | The manifest builds and loads, but a store would reject or flag it as written. |
W_PERMISSION_MISMATCH | The code uses an API or reaches a host that the manifest permissions do not cover the way the code needs. |
W_API_UNSUPPORTED | The code calls an extension API, or a form of one, that the target browser does not have. |
W_WAR_EXPOSURE | A file a script names is not reachable through web_accessible_resources, or the build exposed it more widely than the manifest lists. |
W_CSS_NOT_APPLIED | A stylesheet import or url() is kept in the output but the browser will not apply it where it sits. From the release after 4.2.0, it also marks a PostCSS or stylesheet setup step that did not run, such as a PostCSS config that does not load. Releases up to 4.2.0 gave those warnings W_RESTART_REQUIRED. |
W_ENV_SECRET_PUBLIC | An EXTENSION_PUBLIC_ variable has a name that looks like a secret, and its value is written into the built code. |
W_BUILD_CONSTANT_UNDEFINED | A script reads a build constant that nothing defines, so it throws when it loads. |
W_SCRIPT_WORLD_UNKNOWN | A script is registered at runtime with a world the build cannot read, so it is treated as an isolated world script. |
W_ENV_DEFINE_WRITTEN | Project code writes to an env name that the build replaces with its value, so dotted reads of that name keep the build value. |
W_ENV_NAME_RESERVED | A .env file sets a name the build reserves for the browser or mode it compiles for, so the file value is ignored. |
W_ENV_ASSET_NOT_UTF8 | An emitted .json or .html file holds a $EXTENSION_ placeholder but is not UTF-8 text, so it ships byte for byte and the placeholder is left as written. From the release after 4.2.0. |
W_COMPANION_EXTENSION_PATH | A companion extension entry leads outside the project, is not an unpacked extension folder, or names a folder that does not exist, so the browser opens without it. |
W_CDP_NOT_CONNECTED | A dev, start, or preview session came up with no live CDP transport and stayed ready. Reload and HMR cannot attach. |
W_CDP_TIMEOUT | A CDP command or load timed out after launch, and the dev, start, or preview session stayed ready. Reload and HMR cannot attach. |
W_CDP_OP_FAILED | An extension operation over CDP failed after launch, and the dev, start, or preview session stayed ready. Reload and HMR cannot attach. A fault of any class other than the four with a warning name of their own is reported under this code too. |
W_BROWSER_CONNECTION_CLOSED | The debug socket closed after launch, and the dev, start, or preview session stayed ready. Reload and HMR cannot attach. |
W_EXTENSION_ID_UNKNOWN | The extension id could not be determined over CDP after launch, and the dev, start, or preview session stayed ready. Reload and HMR cannot attach. |
Folded and legacy names
codes.json carries two extra mappings beside the table:
foldedmaps finer inventory names onto a shipped family code. For exampleE_ARG_REQUIREDfolds ontoE_ARGS, andE_BROWSER_NOT_INSTALLEDfolds ontoE_BROWSER_NOT_FOUND.- Eleven
E_*names that only ever marked a warning fold onto theirW_*name, such asE_PORT_IN_USE. Nothing reports them now. legacymaps the three pre-envelope conventions onto the table. Snake_caseready.jsoncodes (profile_lockedtoE_PROFILE_LOCKED), PascalCase error names (TargetNotFoundtoE_TARGET_NOT_FOUND), and kebab-case doctor check ids (eval-tokentoE_TOKEN_MISSING).
Next steps
- See where codes travel in the Result envelope.
- Watch failure frames live in the Lifecycle stream.

