Guides

Debugging

Copy for LLMs
Last updated by
Harlan Wilton
 in doc: clean up.

Introduction

While Unlighthouse handles many edge cases automatically, complex websites may present unique challenges. This guide provides systematic debugging approaches to identify and resolve scanning issues.

Always start with debug logs before trying more advanced debugging techniques.

Debug Logging

Enable Debug Mode

Debug mode provides detailed logs about the scanning process:

unlighthouse --site https://example.com --debug

Browser Inspection

Visual Debugging

Watch the browser perform scans in real-time:

// unlighthouse.config.ts
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: false, // Show browser window
    slowMo: 250, // Slow down actions (ms)
    devtools: true, // Open DevTools automatically
  },
  puppeteerClusterOptions: {
    concurrency: 1, // Single worker for easier debugging
  },
})
Visual debugging significantly slows down scanning. Use only for troubleshooting specific issues.

Advanced Debugging Techniques

Network Debugging

Capture and analyze network traffic:

export default defineUnlighthouseConfig({
  lighthouseOptions: {
    // Save network logs
    extraHeaders: {
      'X-Debug': 'unlighthouse'
    },
  },
  hooks: {
    'page:request': (request) => {
      console.log('Request:', request.url())
    },
    'page:response': (response) => {
      if (!response.ok()) {
        console.error('Failed:', response.url(), response.status())
      }
    },
  },
})

Debugging Specific Issues

Authentication Problems

export default defineUnlighthouseConfig({
  debug: true,
  scanner: {
    // Log authentication attempts
    auth: {
      username: 'user',
      password: 'pass',
    },
  },
  hooks: {
    authenticate: ({ page, route }) => {
      console.log('Authenticating:', route.path)
    },
  },
})

Dynamic Content Issues

export default defineUnlighthouseConfig({
  scanner: {
    // Wait for dynamic content
    waitForSelector: '.main-content',
    waitForTimeout: 5000,
  },
  lighthouseOptions: {
    // Extend timeouts for slow apps
    maxWaitForLoad: 45000,
  },
})

SSL/Certificate Issues

export default defineUnlighthouseConfig({
  puppeteerOptions: {
    // Ignore certificate errors (development only)
    ignoreHTTPSErrors: true,
    args: [
      '--ignore-certificate-errors',
      '--allow-insecure-localhost',
    ],
  },
})

Chrome/Chromium Issues

Many scanning issues relate to Chrome installation or permissions.
export default defineUnlighthouseConfig({
  chrome: {
    // Use bundled Chromium instead of system Chrome
    useSystem: false,
    // Custom Chrome executable
    executablePath: '/usr/bin/google-chrome-stable',
  },
})
Edit this page
Markdown For LLMs
Did this page help you?

Configuration

Learn how to configure Unlighthouse for your specific needs using configuration files and inline options.

Authentication

Configure authentication for scanning protected websites using basic auth, cookies, headers, or custom methods.