Debugging Lighthouse Scans

Enable logs

pnpm exec unlighthouse --site https://example.com --debug

Debug logs show config resolution, route discovery, scan status, and audit failures. Use --debug=false to override configured debug logging.

Check discovery separately

Start with one explicit URL to distinguish discovery problems from audit problems:

pnpm exec unlighthouse-ci --site https://example.com --urls / --reporter json

For JavaScript-rendered navigation, supply a sitemap or explicit URLs. The discovery crawler does not execute JavaScript.

Check Chrome

The local auditor launches Chrome in headless mode. Set CHROME_PATH when Chrome Launcher cannot find your installed browser.

CHROME_PATH=/usr/bin/google-chrome pnpm exec unlighthouse-ci --site https://example.com

puppeteerOptions.headless, slowMo, and page hooks do not control the v1 auditor. See Chrome Options.

Check authentication

Read Authentication before testing protected routes. Browser storage and audit headers do not authenticate the HTML discovery crawler.

Report a failure

Include your Node.js version, package version, command, and relevant debug logs. Remove credentials, tokens, cookies, and private URLs before sharing logs.