Skip to main content
Unblock local development quickly by checking the most common failures first. Use this page as a practical triage path before deeper debugging.

​
Troubleshooting capabilities

​
Fast triage flow

  1. Reproduce with one target (--browser=chromium).
  2. Remove custom profile and binary flags.
  3. Confirm whether the issue happens in dev, build, or both.
  4. Fix one error class at a time (restart, dependency, path, or launch).

​
Quick diagnosis decision tree

​
Common issues

​
Restart required diagnostics

If you see a restart-required error, stop and rerun extension dev. Typical triggers:
  • Manifest entrypoint list changes.
  • Adding/removing files in pages/ or scripts/.
  • Structural HTML script/style entry changes.
See Dev update behavior for the full matrix.

​
Missing optional dependencies

The CLI installs some integrations on demand (for example, Vue/Preact refresh tooling, style preprocessors). If the CLI prompts for optional dependency installation:
  1. Allow the install.
  2. Restart extension dev.
  3. Run again after dependencies finish installing.

​
Browser binary problems

If target browser launch fails:
  • Verify custom binary path (--chromium-binary / --gecko-binary).
  • Confirm browser target is compatible with the provided binary.
  • Fall back to the default chromium target to isolate configuration issues.

​
Build runs but preview shows the wrong code

preview loads dist/<target> when it exists and falls back to the source manifest directory when it does not, so a missing build runs the source as-is instead of failing.
  • Run extension build --browser=<target>.
  • Then run extension preview --browser=<target>.

​
Manifest reference errors

If build reports missing manifest files:
  • Verify paths are relative to manifest location.
  • Verify leading / usage (public-root semantics).
  • Ensure files actually exist in source/public locations.

​
Docker, dev containers, and Codespaces

When running inside a container, the dev server binds to 127.0.0.1 by default, so the host machine cannot reach it.
  • Pass --host 0.0.0.0 to bind to all interfaces.
  • Use --port 0 to let the OS assign a free port if 8080 is taken.
  • If browser connections are slow or flaky in continuous integration (CI) containers, increase the connection timeouts using browser transport tuning variables.

​
Node.js script in scripts/ folder

If the build fails with scripts/ is a reserved folder in Extension.js, you have a Node.js file inside the scripts/ special folder. Extension.js wraps every file in scripts/ with a browser content-script runtime. Node.js-only files fail in this context. Move the file to a different folder at the project root (for example, bin/, tools/, or ci-scripts/). See special folders for details.

​
content_scripts/content-0.css fails with net::ERR_FILE_NOT_FOUND

The console shows a red request for chrome-extension://<id>/content_scripts/content-0.css with net::ERR_FILE_NOT_FOUND, and the extension still works. Before Extension.js 4.1.10, a content script with no stylesheet still requested a sibling content-0.css that the build never emitted. The request is harmless, but it stays red in the console. The fix shipped in 4.1.10, so upgrade:
  • Run npx extension@latest dev to use the latest CLI, or bump the extension dependency in package.json.
If your content script imports a CSS file, or the manifest entry declares css, the file is real and must exist in dist/<browser>/content_scripts/. A missing file in that case is a build problem, not this phantom request.

​
Still blocked after fixes

If the issue persists:
  • Clear temporary assumptions and reproduce from a clean terminal session.
  • Reduce to the smallest manifest/entrypoint case that still fails.
  • Capture the exact command + error output for issue reporting.

​
Debugging checklist

  • Reproduce with a single browser target first (--browser=chromium).
  • Reproduce without custom profile/binary flags.
  • Check whether the issue appears in both dev and build.
  • Keep one change at a time when touching manifest + entrypoint files.

​
Next steps