> ## 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 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](/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.

### 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).