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 fails

preview expects existing build output.
  • 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.

​
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