How can I debug issues occurring in Headless Chromium?

Debugging issues in Headless Chromium can be quite challenging because you don't have the graphical user interface that you'd normally use to inspect elements, view the console, or use other developer tools. However, there are several strategies and techniques you can use to debug issues when running Chromium in headless mode.

1. Enable Verbose Logging

You can start by running Chromium with verbose logging. This will output more information that could help you identify the problem.

For example, you can start Chromium with the --enable-logging --v=1 flags to get verbose logs:

chromium-browser --headless --enable-logging --v=1 --no-sandbox

2. Remote Debugging

Chromium supports remote debugging, and you can use this feature to inspect a headless browser session. To enable remote debugging, you need to start Chromium with the --remote-debugging-port flag.

For example, you can start Chromium with the following flags:

chromium-browser --headless --remote-debugging-port=9222 --no-sandbox

Once Chromium is running with remote debugging enabled, you can navigate to http://localhost:9222 in another browser instance. You will see a list of inspectable pages where you can click on your target page to open the Developer Tools for that page.

3. Take Screenshots

Sometimes, taking a screenshot of the headless browser can give you a clue about what's happening at a particular point in time. You can use the --screenshot flag to take a screenshot:

chromium-browser --headless --screenshot --no-sandbox

You can also take screenshots programmatically using libraries like Puppeteer or Selenium.

4. Dump DOM

You can dump the DOM of the page to understand the current state of the HTML. This can be done by redirecting the standard output to a file:

chromium-browser --headless --dump-dom --no-sandbox > page.html

5. Use Puppeteer for Node.js

If you are using Node.js, Puppeteer is a library that provides a high-level API to control headless Chrome. It has built-in methods to help with debugging, such as page.screenshot() and page.content().

Here's an example of how to use Puppeteer to take a screenshot and dump the DOM:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('');

  // Take a screenshot
  await page.screenshot({ path: 'screenshot.png' });

  // Dump the DOM
  const content = await page.content();

  await browser.close();

6. Use Python with Selenium

If you're using Python, Selenium WebDriver can be used to control headless Chrome. It also allows you to take screenshots and dump the DOM.

from selenium import webdriver
from import Options

chrome_options = Options()
driver = webdriver.Chrome(options=chrome_options)


# Take a screenshot

# Dump the DOM
with open('page.html', 'w') as f:


7. Check Network Traffic

You can monitor the network traffic by capturing the requests and responses. Tools like Puppeteer allow you to listen to network events and log them for debugging purposes.

8. Use Try-Catch and Logging

When writing scripts for headless Chromium, use try-catch blocks and log errors and other relevant information to the console or to a file. This can help you understand where your script is failing.


By using these techniques, you should be able to effectively debug issues in Headless Chromium. It's important to remember that headless browsers can behave slightly differently from non-headless ones, particularly with regard to rendering and JavaScript execution. Therefore, it's crucial to test your scripts thoroughly in both headless and headful modes to ensure consistency.

Related Questions

Get Started Now

WebScraping.AI provides rotating proxies, Chromium rendering and built-in HTML parser for web scraping