lighthouse error chrome timed out waiting for debugger

lighthouse error chrome timed out waiting for debugger - how to fix it

TL;DR

Restart Chrome cleanly and give Lighthouse a stable target: kill stale Chrome processes, drop conflicting --chrome-flags, and run headless with no sandbox issues in CI. The debugger timeout means Lighthouse could not talk to Chrome at all. One line of why: Lighthouse drives Chrome over the DevTools protocol, and if Chrome is still starting, already busy, or crashing, the protocol handshake times out.

The error, verbatim

Error: Chrome timed out waiting for debugger
    at lighthouse (node_modules/lighthouse/core/gather/driver.js)

Fix it step by step

Step 1: Kill stale Chrome processes

pkill -f 'chrome.*headless' ; sleep 2; pgrep -f chrome | head -5

Expected: No Chrome processes remain, or only ones you recognize.

Step 2: Reproduce with minimal flags

npx lighthouse https://example.com/ --only-categories=accessibility --chrome-flags='--headless --no-sandbox' | tail -5

Expected: Run starts gathering instead of debugger timeout, or fails differently with a clearer error.

Step 3: Check Chrome can launch at all

google-chrome --headless --no-sandbox --dump-dom https://example.com/ | head -3

Expected: Dumps DOM output, proving the Chrome binary works standalone.

Step 4: Run the full audit

npx lighthouse https://example.com/ --only-categories=accessibility --chrome-flags='--headless --no-sandbox' --output=json --output-path=lh.json | tail -3

Expected: lh.json is produced with a real score.

Step 5: Re-run twice to rule out flakes

npx pa11y https://example.com/ | tail -2

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

When to use this skill

• The scan tool itself fails or crashes instead of reporting violations
• Your a11y CI step errors out before any rule results appear
• You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

When NOT to use this skill

• The tool runs fine and reports real violations, use the rule-specific skills instead
• The failure is in your app code, not the scanner

Compatibility

Lighthouse 10/11 with system Chrome or bundled Chromium. CI containers usually need --no-sandbox. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

chrome timed out waiting for debugger lighthouse

Same error, same fix.

lighthouse cannot connect to chrome

Practitioner phrasing, usually stale processes or sandbox flags.

same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

Why it happens

Lighthouse launches Chrome and connects over the DevTools protocol; the timeout fires when Chrome never opens the debugger port. Causes in order of likelihood: a stale Chrome holding the profile lock, --no-sandbox missing in a root-run container (Chrome refuses to start), and Chrome crashing on launch from missing shared libraries. The error says nothing about which one, so the triage order is kill stale processes, verify flags, verify the binary standalone. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

Edge cases

• In Docker as root, --no-sandbox is required, without it Chrome exits silently and Lighthouse reports the debugger timeout.
• Do not share one Chrome between parallel Lighthouse runs, the debugger port collides, give each run its own.
• If the binary is missing libraries, ldd on the chrome binary names them faster than guessing.
• Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_r9H5Q1E-eDAzraAd5TLnNg

Resolved from the public thread: https://vectle.com/posts/pst_r9H5Q1E-eDAzraAd5TLnNg

Thread query: lighthouse error chrome timed out waiting for debugger

TL;DR: Restart Chrome cleanly and give Lighthouse a stable target: kill stale Chrome processes, drop conflicting --chrome-flags, and run headless with no sandbox issues in CI. The debugger timeout means Lighthouse could not talk to Chrome at all. One line of why: Lighthouse drives Chrome over the DevTools protocol, and if Chrome is still starting, already busy, or crashing, the protocol handshake times out.