--- title: "Debugging Lighthouse Scans" description: "Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools." keywords: - lighthouse debug - lighthouse troubleshooting - lighthouse not working - puppeteer debug - lighthouse scan failing navigation: title: "Debugging" relatedPages: - path: /guide/guides/common-errors title: Common Errors - path: /guide/guides/config title: Configuration - path: /guide/guides/puppeteer title: Puppeteer Configuration --- 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](/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