Skip to main content
Guides

Common Errors

View as Markdown

Chrome cannot launch

If Chrome Launcher cannot find a browser, install Chrome in the environment running Unlighthouse. Set CHROME_PATH to that browser executable:

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

If Chrome starts but connection fails, check firewall rules and browser permissions. If you use WSL, install Chrome inside WSL. Legacy chrome.useSystem and Puppeteer executable options do not configure the v1 local auditor. See Chrome Dependency for supported settings.

Config hooks fail

If config loading raises CONFIG_INVALID for hooks, remove the config-file hooks property. Register supported events on host.hooks before starting a programmatic scan. Use onResolvedConfig for the host factory config callback. See Migrating to v1.

Routes are missing

If links need JavaScript, supply explicit urls or a sitemap. The HTML crawler does not execute JavaScript or receive Lighthouse authentication headers. See URL Discovery and Authentication.

Enable logs

Run the failing command with --debug. See Debugging for a single-route check.

Edit this page
Markdown For LLMs
Did this page help you?
Anything that could be done better? :)
Help us improve this page. You can edit this page on GitHub or provide anonymous feedback below.

Related

DebuggingChrome DependencyChrome Options

Chrome Dependency

Chrome Dependency for the Unlighthouse v1 beta.

Device Configuration

Run Unlighthouse in desktop mode with the --desktop flag: pnpm exec unlighthouse --site <url> --desktop. Configure mobile, desktop, or custom viewports with throttling.