Guides

Common Errors

Copy for LLMs
Last updated by
Harlan Wilton
 in chore: lint markdown.

Introduction

This guide covers the most common issues encountered when running Unlighthouse scans and their solutions. Always 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?

Chrome Dependency

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

Device Configuration

Configure device emulation settings for mobile and desktop scanning with custom dimensions and throttling options.