Skip to main content
Some manifest shapes make Chromium refuse to load the whole extension. The refusal surfaces as a native dialog, or as nothing at all, never as a console error. Without help, a dev session just wedges: the browser runs, the extension is absent, and the debug channel never attaches. Extension.js closes that gap in two places:
  • Before launch, it reads the built manifest.json of every extension it is about to load and finds each refusal it can prove, naming the field and the reason. Up to 4.1.41, it warns before the browser starts. From the release after 4.1.41, it holds that prediction until the browser answers, and one block prints per refusal, with the browser’s sentence.
  • At build time, it repairs a small set of unambiguous fatal shapes and prints a fix line for each repair.

What a refused load prints

From the release after 4.1.41, Extension.js holds its own prediction until the browser answers. When the browser refuses the extension, one block prints, with the browser’s sentence:
  • REASON holds the browser’s own words, on one line.
  • A CAUSE line follows when the manifest shows why and the browser’s words do not say it. See Firefox refusals.
  • The prediction prints only when the browser cannot be asked.
  • If the browser loads a shape that was predicted to be refused, one warning says that the browser loaded it and names the shape.
What happens next depends on the command:
  • start and preview: the command stops the browser and exits with code 1.
  • dev: the session stays up and tries the load again on the next save.
Every surface answers a refused load with the code E_EXTENSION_LOAD_REFUSED:
  • start, preview, dev --wait, start --wait, and the act commands (eval, storage, and the others) answer status load-refused and exit with code 1.
  • The dev --output json stream carries the same status and code.
  • doctor --output json keeps status unhealthy and carries the code.
A stopped session that ended on a refusal still names it. doctor and the act commands answer with the refusal and the same code.

Pre-launch diagnosis

These checks run against the built extension, right before the browser spawns. From the release after 4.1.41, a finding waits for the browser’s answer. See What a refused load prints.

Manifest version refusals

A manifest_version above 3 is not in this table, because Chromium loads it. See Shapes that Chromium loads. Manifest V2 support differs by browser:
  • Chrome: Chrome 138 was the last version to support Manifest V2, as Google’s Manifest V2 support timeline states.
  • Chromium: Chromium 151 removed the last flag that loaded a Manifest V2 extension unpacked.
  • Microsoft Edge: Edge has deprecated Manifest V2 and still runs it. Edge 157 loaded and ran an unpacked Manifest V2 extension with no warning, measured on 2026-11-15. Microsoft’s timeline names no final version.
  • Firefox and Safari: both keep Manifest V2.
A Manifest V2 theme, a manifest with a theme key, is not flagged. Chrome 151 still installs it. A build of a Manifest V2 extension for a Chromium target prints one warning with those versions and the ways out:
An Edge build prints a deprecation notice with the same options, because Edge still runs Manifest V2. An Edge session launches the extension and does not count the manifest as a refusal:

One verdict per session

A Manifest V2 project on a Chromium target hears the verdict once per session:
  • dev and start: the build warning above says it. No second line prints before the launch.
  • preview: no build runs, so one line says it before the launch.
On a target that refuses Manifest V2, start and preview then stop with this exit message:
From the release after 4.1.41, the first line of that message reads Chrome refuses to load this extension, so nothing in it runs. When the browser gave its own sentence, the message carries it on a REASON line and ends with Fix what the browser names, then run the command again. A dev session stays up after the build warning. The refusal that the browser reports is recorded in ready.json as extension_load_refused, and in extension logs. The terminal does not print it a second time. A refusal for any other reason still prints. From the release after 4.1.41, the Manifest V2 case keeps this rule. Its verdict is the one prediction that does not wait for the browser. The build warning says it under dev and start, and the line above prints before the launch under preview. Every other prediction is held. See What a refused load prints.

Invalid match patterns

Where an invalid pattern sits decides what the browser does:
  • content_scripts[].matches, content_scripts[].exclude_matches, or web_accessible_resources[].matches: Chrome refuses the whole extension.
  • host_permissions or optional_host_permissions: Chrome and Firefox load the extension and drop the pattern. The pattern grants no host access, Chrome records no error or warning, and the other patterns in the list still apply.
The host grammar allows *, *.domain.tld, or a literal host. Any other wildcard placement in the host is invalid, for example https://foo.*.com/*. Ports, query strings, and fragments do not trigger a refusal, and the port may itself be a wildcard. From the release after 4.1.41, Extension.js prints a warning that names each dropped pattern. It prints during build, dev, and start, and before preview launches:

The load-blocker catalogue

Each of these was verified to refuse the whole extension on a live Chrome build:
  • name: missing, empty, or not a string. Chrome requires a non-empty string name.
  • version: missing, or not 1 to 4 dot-separated integers, each 0 to 65535.
  • MV3 web_accessible_resources: entries must be dictionaries with resources, plus one of matches, extension_ids, or use_dynamic_url. The MV2 string-array form refuses on MV3. MV2 keeps it legal.
  • content_scripts grammar: matches is required and must not be empty, js and css entries must be strings, run_at accepts only document_start, document_end, or document_idle, and each entry needs at least one js or css file.
  • minimum_chrome_version: an invalid value refuses outright. A valid value above the resolved browser’s version refuses too, so the check compares against the binary that the session launches.
  • commands: Chrome allows at most 4 shortcuts with a suggested_key. Firefox has no cap, so ported Firefox extensions routinely trip this.
  • key: must be a valid base64 public key. Broken padding refuses the extension.
  • Icons: a manifest icon (icons.* or any *_action.default_icon) whose file is missing or 0 bytes refuses the whole extension.
  • Locales: a declared default_locale whose _locales/<locale>/messages.json is missing or not valid JSON refuses. So does a whole-string __MSG_key__ reference that the catalog does not define (the lookup is case-insensitive, @@predefined names are exempt). A populated _locales tree with no default_locale in the manifest refuses too.
  • storage.managed_schema: a schema path that does not exist inside the extension directory refuses the whole extension.
From 4.2.0, a field that holds a file path must hold a string. A number, an array, or an object in that place, such as "js": [42] or "options_page": 1, stops the build with E_MANIFEST_INVALID. The message names the field, as in The content_scripts[0].js[0] field in your manifest.json must be a file path string. Each finding prints as a warn naming the extension path and every blocker, before the spawn, so the wedge is explained up front. From the release after 4.1.41, the finding prints only when the browser cannot be asked.

Shapes that Chromium loads

Chromium loads two manifest shapes that you may expect it to refuse. Both were measured on Chrome 151.
  • Manifest V3 with background.scripts and no background.service_worker: the extension loads, gets an extension ID, and shows no error. The scripts never start. Extension.js warns and launches.
  • A manifest_version above 3: the extension loads and runs as Manifest V3, with no warning from the browser. Firefox refuses it. From the release after 4.1.41, the Extension.js build refuses a manifest_version other than the integer 2 or 3 on every target.

Firefox refusals

These results were measured on Firefox Nightly 160.
  • background.service_worker alone: Firefox refuses the extension. Its reason reads background.service_worker is currently disabled. Add background.scripts. An Extension.js build for Firefox writes background.scripts for you. See Background scripts.
  • A strict_min_version above the running version: this is not a refusal on a temporary add-on load.
  • A manifest_version that Firefox does not load: Firefox’s own words do not name the version. From the release after 4.1.41, a CAUSE line names what the manifest shows. It reads Firefox does not load a manifest_version above 3. or Firefox loads only the integer 2 or 3 as manifest_version.

Automatic repairs at build time

A subset of fatal shapes is unambiguous enough to fix. During the build, Extension.js repairs these in the emitted manifest.json: Every repair reports a fix line in the CLI output at the moment it happens, and records a manifest.json build warning, so nothing is rewritten silently. Some repairs apply to one browser target only. See Cross-browser compatibility for the list.
Repairs apply to the emitted dist manifest only. Your source manifest.json is never modified. Fix the source when you see a fix line, so the repair stops being needed.

Next steps