---
title: "Debugging Lighthouse Scans"
description: "Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools."
canonical_url: "https://unlighthouse.dev/guide/guides/debugging"
---

> Index of every page on this site: [llms.txt](https://unlighthouse.dev/llms.txt)

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

## Start Here: Debug Logs

90% of issues become obvious with debug logging:

```bash
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

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

```ts
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)

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

## Common Issues

### Pages Timing Out

Your site might be slow or have heavy JavaScript:

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

### SPA Not Rendering

JavaScript apps need time to hydrate:

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

### SSL/Certificate Errors

On localhost or staging with self-signed certs:

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

### Chrome Won't Start

Try using bundled Chromium instead of system Chrome:

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

Or point to a specific Chrome:

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

### Failed Network Requests

Log all failed requests to find what's breaking:

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

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

## Sitemap

See the full [sitemap](https://unlighthouse.dev/sitemap.md) for all pages.
