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

AreaWhat this helps you verify
Restart diagnosticsWhether a restart is required for structural changes
Dependency setupWhether optional tooling is missing for the current stack
Browser launchWhether target/browser binary config is valid
Build/preview flowWhether output exists for preview and matches target
Manifest pathsWhether referenced files resolve correctly

​
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

If this fails…Check firstNext action
Extension does not loadBuild and manifest errorsVerify referenced files and rerun dev
Browser does not launch--browser + binary pathRemove custom binary/profile flags and retry
Changes are not updatingUpdate type (hot module replacement vs restart-required)Review dev update behavior and restart when required
preview failsExisting dist/<browser> outputRun extension build --browser=<target> first
Runtime still brokenMinimal reproducible setupReduce scope and capture exact command + error

​
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
  • fallback to default chromium target to isolate config 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, devcontainers, 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.
extension dev --host 0.0.0.0 --port 0

​
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