---
title: "Common Errors · Unlighthouse"
meta:
  "og:description": "Troubleshoot common issues encountered when running Unlighthouse scans, including browser connection and environment problems."
  "og:title": "Common Errors · Unlighthouse"
  description: "Troubleshoot common issues encountered when running Unlighthouse scans, including browser connection and environment problems."
---

**Guides**

# **Common Errors**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/common-errors.md)

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**](https://unlighthouse.dev/guide/guides/debugging).

## [`connect ECONNREFUSED 127.0.0.1:<port>`](#connect-econnrefused-127001port)

**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**

- Install Puppeteer on WSL following the [**documentation**](https://pptr.dev/troubleshooting#running-puppeteer-on-wsl-windows-subsystem-for-linux).
- Install Chrome in WSL following the [**documentation**](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#install-google-chrome-for-linux).

**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](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/common-errors.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/common-errors.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/common-errors.md) on GitHub or provide anonymous feedback below.

[**Chrome Dependency** Configure Chrome browser settings for Unlighthouse scanning, including system Chrome usage and custom installations.](https://unlighthouse.dev/guide/guides/chrome-dependency) [**Device Configuration** Run Unlighthouse in desktop mode with --desktop flag or device: 'desktop' config. Configure mobile/desktop emulation, viewports, and throttling.](https://unlighthouse.dev/guide/guides/device)