- Before launch, it reads the built
manifest.jsonof 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:REASONholds the browser’s own words, on one line.- A
CAUSEline 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.
startandpreview: the command stops the browser and exits with code1.dev: the session stays up and tries the load again on the next save.
E_EXTENSION_LOAD_REFUSED:
start,preview,dev --wait,start --wait, and the act commands (eval,storage, and the others) answer statusload-refusedand exit with code1.- The
dev --output jsonstream carries the same status and code. doctor --output jsonkeeps statusunhealthyand carries the code.
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.
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:
One verdict per session
A Manifest V2 project on a Chromium target hears the verdict once per session:devandstart: 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.
start and preview then stop with this exit message:
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, orweb_accessible_resources[].matches: Chrome refuses the whole extension.host_permissionsoroptional_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.
*, *.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 withresources, plus one ofmatches,extension_ids, oruse_dynamic_url. The MV2 string-array form refuses on MV3. MV2 keeps it legal. content_scriptsgrammar:matchesis required and must not be empty,jsandcssentries must be strings,run_ataccepts onlydocument_start,document_end, ordocument_idle, and each entry needs at least onejsorcssfile.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 asuggested_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_localewhose_locales/<locale>/messages.jsonis 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,@@predefinednames are exempt). A populated_localestree with nodefault_localein the manifest refuses too. storage.managed_schema: a schema path that does not exist inside the extension directory refuses the whole extension.
"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.scriptsand nobackground.service_worker: the extension loads, gets an extension ID, and shows no error. The scripts never start. Extension.js warns and launches. - A
manifest_versionabove 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 amanifest_versionother than the integer 2 or 3 on every target.
Firefox refusals
These results were measured on Firefox Nightly 160.background.service_workeralone: Firefox refuses the extension. Its reason readsbackground.service_worker is currently disabled. Add background.scripts.An Extension.js build for Firefox writesbackground.scriptsfor you. See Background scripts.- A
strict_min_versionabove the running version: this is not a refusal on a temporary add-on load. - A
manifest_versionthat Firefox does not load: Firefox’s own words do not name the version. From the release after 4.1.41, aCAUSEline names what the manifest shows. It readsFirefox does not load a manifest_version above 3.orFirefox 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 emittedmanifest.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
- Debugging overview: the full control surface for a running session.
- Browsers available: choose a target that can load your manifest.
- Cross-browser compatibility: keep one manifest working per engine.

