Troubleshooting

    Unblock local development quickly by checking the highest-signal 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 (HMR 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

    Some integrations are installed on demand (for example Vue/Preact refresh tooling, style preprocessors).

    If the CLI prompts for optional dependency installation:

    1. allow install
    2. restart extension dev
    3. rerun 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

    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 dev and build both.
    • Keep one change at a time when touching manifest + entrypoint files.

    Next steps