---
title: "Debugging Lighthouse Scans · Unlighthouse"
meta:
  "og:description": "Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools."
  "og:title": "Debugging Lighthouse Scans · Unlighthouse"
  description: "Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools."
---

**Guides**

# **Debugging Lighthouse Scans**

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

Scan not working? Here's how to figure out why.

## [Start Here: Debug Logs](#start-here-debug-logs)

90% of issues become obvious with debug logging:

```
unlighthouse --site example.com --debug
```

This shows you:

- What URLs are being discovered
- Which pages are being scanned
- Any errors or timeouts
- Chrome connection status

## [Watch the Browser](#watch-the-browser)

Can't tell what's happening? Watch it:

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: false, // Show the browser window
    slowMo: 250, // Slow down so you can see what's happening
    devtools: true, // Open Chrome DevTools
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1, // One page at a time
  },
})
```

Now you'll see exactly what Unlighthouse sees—useful for:

- Auth issues (is login working?)
- JavaScript errors (check the console)
- Missing content (is the page rendering?)
- Blocked requests (check Network tab)

Visual mode is slow. Only use it to diagnose specific problems.

## [Common Issues](#common-issues)

### [Pages Timing Out](#pages-timing-out)

Your site might be slow or have heavy JavaScript:

```
export default defineUnlighthouseConfig({
  lighthouseOptions: {
    maxWaitForLoad: 60000, // Wait up to 60s (default: 45s)
  },
})
```

### [SPA Not Rendering](#spa-not-rendering)

JavaScript apps need time to hydrate:

```
export default defineUnlighthouseConfig({
  scanner: {
    skipJavascript: false, // Wait for JS to execute
  },
  lighthouseOptions: {
    maxWaitForLoad: 45000,
  },
})
```

### [SSL/Certificate Errors](#sslcertificate-errors)

On localhost or staging with self-signed certs:

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    ignoreHTTPSErrors: true,
    args: ['--ignore-certificate-errors'],
  },
})
```

### [Chrome Won't Start](#chrome-wont-start)

Try using bundled Chromium instead of system Chrome:

```
export default defineUnlighthouseConfig({
  chrome: {
    useSystem: false, // Download and use bundled Chromium
  },
})
```

Or point to a specific Chrome:

```
export default {
  puppeteerOptions: {
    executablePath: '/usr/bin/google-chrome-stable',
  },
}
```

### [Failed Network Requests](#failed-network-requests)

Log all failed requests to find what's breaking:

```
export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      page.on('requestfailed', (req) => {
        console.log('❌ Failed:', req.url(), req.failure()?.errorText)
      })
    },
  },
})
```

## [Still Stuck?](#still-stuck)

1. Check [**Common Errors**](https://unlighthouse.dev/guide/guides/common-errors) for known issues
2. Search [**GitHub Issues**](https://github.com/harlan-zw/unlighthouse/issues)
3. Ask on [**Discord**](https://discord.gg/275MBUBvgP) with your debug logs

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/1.debugging.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/debugging.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/1.debugging.md) on GitHub or provide anonymous feedback below.

[**Configuration** Configure Unlighthouse for your specific needs using configuration files and inline options.](https://unlighthouse.dev/guide/guides/config) [**Authentication** Scan password-protected websites with Unlighthouse. Configure basic auth, cookies, headers, localStorage, and programmatic login flows.](https://unlighthouse.dev/guide/guides/authentication)

**On this page **

- [Start Here: Debug Logs](#start-here-debug-logs)
- [Watch the Browser](#watch-the-browser)
- [Common Issues](#common-issues)
- [Still Stuck?](#still-stuck)