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.

​
Extension pages reload with ?rspack-dev-server-hot=false in the URL

In extension dev, the URL of an options, popup, or sidebar page ends with ?rspack-dev-server-hot=false&webpack-dev-server-hot=false. Each edit reloads the whole page instead of updating it in place. From 3.18.1 to 4.1.9, Extension.js added these parameters on purpose. They turned off hot module replacement on HTML pages, so pages fell back to a full reload. Version 4.1.10 turns hot module replacement on for these pages and removes the old parameters from the URL. Upgrade:
  • Run npx extension@latest dev to use the latest CLI, or bump the extension dependency in package.json.

​
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