Guides

Debugging Lighthouse Scans

Copy for LLMs

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

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

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

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

JavaScript apps need time to hydrate:

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:

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

Chrome Won't 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

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?

  1. Check Common Errors for known issues
  2. Search GitHub Issues
  3. Ask on Discord with your debug logs
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.

Configuration

Configure Unlighthouse for your specific needs using configuration files and inline options.

Authentication

Scan password-protected websites with Unlighthouse. Configure basic auth, cookies, headers, localStorage, and programmatic login flows.