> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Extension.js issues

> Fix common Extension.js issues with a practical triage path. Covers restart diagnostics, dependency setup, browser launch, and manifest errors.

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

## Troubleshooting capabilities

| Area | What this helps you verify |
| - | - |
| Restart diagnostics | Whether a restart is required for structural changes |
| Dependency setup | Whether optional tooling is missing for the current stack |
| Browser launch | Whether target/browser binary configuration is valid |
| Build/preview flow | Whether output exists for preview and matches target |
| Manifest paths | Whether 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 first | Next action |
| - | - | - |
| Extension does not load | Build and manifest errors | Verify referenced files and rerun `dev` |
| Browser does not launch | `--browser` + binary path | Remove custom binary/profile flags and retry |
| Changes are not updating | Update type (hot module replacement vs restart-required) | Review [Dev update behavior](/docs/workflows/dev-update-behavior) and restart when required |
| `preview` fails | Existing `dist/<browser>` output | Run `extension build --browser=<target>` first |
| Runtime still broken | Minimal reproducible setup | Reduce 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](/docs/workflows/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](/docs/features/environment-variables#browser-transport-tuning-variables).

```bash theme={null}
extension dev --host 0.0.0.0 --port 0
```

### 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](/docs/features/special-folders#nodejs-scripts-are-not-allowed-in-scripts) 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

* Review [Security checklist](/docs/workflows/security-checklist).
* Review [Performance playbook](/docs/workflows/performance-playbook).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.