Guides

Common Errors

Copy for LLMs

Solutions for frequently encountered issues when running Unlighthouse scans. Ensure you're using the latest version before troubleshooting.

For general debugging techniques, see the Debugging Guide.

connect ECONNREFUSED 127.0.0.1:<port>

Example

Error: Unable to launch browser for worker, error message: connect ECONNREFUSED 127.0.0.1:51667

This error is thrown when Chromium is unable to launch. This happens when puppeteer is unable to connect to the browser. This can be from a number of reasons:

  • The environment is not configured correctly, likely when using Windows and WSL.
  • You have a firewall or antivirus blocking Chrome or Chromium from launching or connecting to the required port.
  • You are using an unsupported version of Chrome or Chromium.

Windows and WSL Solution

Other Environments

  • You can try disabling the system Chrome, instead using the fallback.
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false,
  },
})
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 DependencyPuppeteer Configuration

Chrome Dependency

Configure Chrome browser settings for Unlighthouse scanning, including system Chrome usage and custom installations.

Device Configuration

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