This article is about fixing [Bug]: Missing X server or $DISPLAY in Puppeteer puppeteer
  • 25-Jan-2023
Lightrun Team
Author Lightrun Team
This article is about fixing [Bug]: Missing X server or $DISPLAY in Puppeteer puppeteer

[Bug]: Missing X server or $DISPLAY in Puppeteer puppeteer

Lightrun Team
Lightrun Team

Explanation of the problem

The problem that you are encountering is related to the execution of the crawlsite.js function located at puppeteer/examples/crawlsite.js path in the puppeteer git repository. The error message displayed is as follows:

[186875:186875:0318/] Missing X server or $DISPLAY [186875:186875:0318/] The platform failed to initialize. Exiting.

This error message suggests that the X server or $DISPLAY is missing and the platform is unable to initialize. As a result, the execution of the function is terminated.

Upon further investigation, it was found that the issue is related to the headless configuration of the Chrome browser. The function executes correctly when the headless configuration is set to true, but when set to false, the Chrome browser fails to launch and the aforementioned error message is displayed.

To resolve this issue, the following steps can be taken:

  • Ensure that the X server or $DISPLAY is properly configured and running on the system.
  • Verify the following code block for correctness:
const browser = await puppeteer.launch({
  headless: false, // <-- change this to false

It is important to make sure that the browser is launched with headless false to allow the Chrome browser to be launched.

  • Check the value of $DISPLAY variable, it should be set to the correct value. For example, on most systems, it should be set to “:0”, which indicates the first available display. If the value is not set or has the incorrect value, you can set the value using the following code block:
process.env.DISPLAY = ':0'

Troubleshooting with the Lightrun Developer Observability Platform

Getting a sense of what’s actually happening inside a live application is a frustrating experience, one that relies mostly on querying and observing whatever logs were written during development.
Lightrun is a Developer Observability Platform, allowing developers to add telemetry to live applications in real-time, on-demand, and right from the IDE.

  • Instantly add logs to, set metrics in, and take snapshots of live applications
  • Insights delivered straight to your IDE or CLI
  • Works where you do: dev, QA, staging, CI/CD, and production

Start for free today

Problem solution for [Bug]: Missing X server or $DISPLAY

The problem of encountering “Missing X server or $DISPLAY” error when running the crawlsite.js function in puppeteer can be caused by the system’s inability to find the X server or the $DISPLAY variable. This error message is common when running puppeteer on Linux or Unix-based systems as the X server is required for GUI-based applications.

One solution that worked for some users is to find the display variable with the command “printenv DISPLAY” on the terminal session that is open on RDP. This is a solution that worked on Debian 11. Another solution is to set the environment variable DISPLAY to the correct value.

    env: {
        DISPLAY: ":10.0"

This solution worked for users who are running puppeteer on Ubuntu 22.04 and encountering the error message even though Chromium can launch in the RDP session via RDP terminal or via remote ssh with DISPLAY set to :10.0. This indicates that puppeteer is launching Chrome/Chromium in a different way and requires the environment variable to be set manually.

If the problem persists, it is recommended to refer to the puppeteer troubleshooting guide for further assistance.

Other popular problems with Puppeteer puppeteer

Problem: “Error: Failed to launch chrome!”

This error message is encountered when puppeteer is unable to launch the Chrome browser. This can be caused by missing dependencies, outdated versions of Chrome, or incorrect path to the Chrome executable.


Verify that all dependencies are installed and up-to-date, make sure that you have the latest version of Chrome installed, check that the path to the Chrome executable is correct in your code. If the problem persists, refer to the puppeteer troubleshooting guide for further assistance.

Problem: “Error: Navigation Timeout Exceeded”

This error message occurs when puppeteer is unable to navigate to a website within the specified timeout period. This can be caused by slow internet connection, blocked resources, or incorrect navigation code.


Increase the navigation timeout period, check for any blocked resources or network issues, and verify that the correct URL is being used and that no typos are present in the navigation code.

Problem: “Error: Protocol error (Runtime.callFunctionOn): Target closed.”

This error message occurs when puppeteer is trying to interact with a closed browser window or an element that is no longer present on the page. This can be caused by incorrect usage of puppeteer functions or a lack of proper error handling in the code.


Check the code for any instances where a browser window or element is being closed before puppeteer has a chance to interact with it, use try-catch statements to handle any potential errors, and verify that the selectors used to locate elements on the page are correct and that the elements are present on the page at the time of interaction. Additionally, ensure that the page is fully loaded before attempting to interact with elements on it.

A brief introduction to Puppeteer puppeteer

Puppeteer is a Node.js library that provides an API for controlling Chrome or Chromium browsers. It allows developers to automate browser tasks, such as clicking buttons, filling out forms, and navigating between pages. Puppeteer also provides a powerful set of tools for interacting with web pages, such as the ability to take screenshots, generate PDFs, and emulate different devices.

Puppeteer is built on top of the DevTools protocol, which is the same protocol used by Chrome’s developer tools. This means that all of the browser’s internal features, such as the DOM, CSS, and JavaScript engines, can be controlled and accessed through puppeteer. Additionally, puppeteer allows for the creation of headless browsers, which run without a GUI, making it ideal for automation and testing tasks. Puppeteer also supports multithreading, which enables parallel execution of multiple browser instances.

Most popular use cases for Puppeteer puppeteer

  1. Web Scraping and Data Extraction: Puppeteer can be used to automate the process of extracting data from websites. By using the built-in page navigation and element selection functions, developers can easily access and extract data from web pages. For example, the following code block uses Puppeteer to navigate to a website, extract the text content of a specific element and save it in a variable:
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('');
  const elementText = await page.$eval('#element-id', el => el.textContent);
  await browser.close();
  1. Browser Automation: Puppeteer can be used to automate repetitive tasks such as filling out forms, clicking buttons, and navigating between pages. This can be useful for testing purposes, as well as for automating repetitive tasks such as data entry. For example, the following code block uses Puppeteer to fill out a form on a website and submit it:
await page.type('#username', 'myusername');
await page.type('#password', 'mypassword');
  1. Generating Reports: Puppeteer can be used to generate reports in various formats such as PDF and PNG. This can be useful for creating screenshots or generating PDF versions of web pages. It also allows for the creation of headless browsers, which can be useful for automating the generation of reports without the need for a GUI. For example, the following code block uses Puppeteer to generate a PNG screenshot of a website:
await page.screenshot({path: 'example.png'});

It’s Really not that Complicated.

You can actually understand what’s going on inside your live applications.

Try Lightrun’s Playground

Lets Talk!

Looking for more information about Lightrun and debugging?
We’d love to hear from you!
Drop us a line and we’ll get back to you shortly.

By submitting this form, I agree to Lightrun’s Privacy Policy and Terms of Use.