Skip to main content
Use doctor to find out why a dev session (or an automation verb talking to it) is not working. doctor walks the control-channel legs of a dev session in dependency order (from the on-disk readiness contract all the way to a live probe of the in-extension executor) and names the first failing leg with a concrete fix, instead of the dead-end error each command gives on its own.

When to use doctor

  • extension logs or an act verb can’t connect and you want to know which leg is broken.
  • An agent or script drives a session via ready.json and needs a machine-readable health check.
  • A dev session looks alive but the extension stopped responding.

Usage

If you omit the path, Extension.js diagnoses the session for the current working folder.

Arguments and flags

How doctor picks the session

Without --browser, doctor diagnoses the session that exists, not a hardcoded default. It lists the ready contracts under dist/extension-js/ and resolves from there:
  • Exactly one live contract wins outright.
  • With several contracts, chromium wins when present, otherwise the first one alphabetically. A session-resolution warn check then names every candidate before the numbered checks run.
  • With no contracts at all, doctor falls back to chromium.
From the release after 4.1.39, a session that still runs wins over one that has ended. A session has ended when its contract reads status: "stopped" or its process is gone. With one session running and the others ended, doctor diagnoses the running one. When every session has ended, doctor diagnoses one of them by the same rule, and the session-resolution check says so:
For a stopped session, the ready-contract check then fails and its remediation names the command that starts the session again. From the release after 4.1.41, when that session ended on a load refusal, the check names the refusal and doctor answers E_EXTENSION_LOAD_REFUSED.

What it checks

Checks run in dependency order. When a leg fails, later checks that depend on it are marked skip and name the check that blocked them: a skip is not a pass. A zeroth session-resolution check appears only when several live sessions exist. It warns and names the session that the run diagnoses. From the release after 4.1.39, it also appears when several sessions exist and all of them have ended. Two more checks run before the numbered ones. engine fails when the session runs the chromium-emulator target, which doctor cannot diagnose. peer-rspack needs only the project, so it runs with or without a dev session. It fails when a direct dependency declares an @rspack/core peer range that misses the version Extension.js ships. That mismatch is why npm install fails with ERESOLVE, and the remediation names the upgrade to run. Some legs have deliberate soft answers:
  • port-agreement passes when no port file exists yet. A first session for this project and browser has nothing to disagree with.
  • executor reports warn, not fail, within 10 seconds of a fresh compile. The service worker may still be attaching. Wait for runtime: "attached" in ready.json before acting.
  • From the release after 4.1.41, executor fails at once for a build with no background that the browser runs. The row carries the same sentence that eval prints. See Refusals on a start or preview session.
  • browser reports skip when the contract has no cdpPort stamped and no exit recorded. Absence of exit evidence is not proof of a live browser.
The pretty output prints one line per check plus the first failing check’s remediation. Each status has a glyph: ✓ pass, ✗ fail, ! warn, – skip. The exit code is 0 when nothing failed and 1 when any check failed, so CI and scripts can gate on it directly.

Sessions from start and preview

From the release after 4.1.39, doctor also diagnoses an extension start or extension preview session that has a control channel, which is one started with --allow-control or --allow-eval. The rows name that command where they named the dev server. Such a session runs no dev server and persists no control port, so port-agreement is not applicable. The row prints as a skip and leaves the pass count, and the header says so:
Under --output json, the row carries "applicable": false:
A start or preview run that holds its browser open without a control channel gives doctor nothing to reach. The ready-contract check fails, says that the command is running with no control channel, and names the command that restarts it with one:
On Firefox, the rows say background page where a Chromium session says service worker, because Firefox runs the background as a page.

Machine-readable output

--output json prints one schema-1 envelope. The check results ride in value on both verdicts, because an unhealthy report is still a report:
A healthy run answers ok: true with status: "healthy" and error: null. From the release after 4.1.41, a run that finds a load refusal keeps status: "unhealthy" and carries error.code: "E_EXTENSION_LOAD_REFUSED". See Manifest refusals. status on each check is pass, fail, warn, or skip. remediation is present on failures that have a known fix. The envelope’s error.code maps from the first failing check:

Typical flow

  1. Start a session: extension dev --browser=chromium --allow-control (add --allow-eval for the eval verb).
  2. When a follow-up command can’t reach it, run extension doctor from the same project root.
  3. Apply the remediation printed for the first failing check, then re-run doctor to confirm.

Next steps

  • Read the readiness contract doctor starts from in dev.
  • Stream extension logs from a healthy session with Debugging.
  • Review shared flags in Global flags.