Missing X server to start the headful browser. Either set headless to true or use xvfb-...

Error

Missing X server to start the headful browser. Either set headless to true or use xvfb-run to run your Puppeteer script.

What it means

Puppeteer raised this from its browser launch code. In practice, it usually means your script reached a browser, page, frame, element, or option state that the API cannot use safely.

How to fix it

• Run in headless mode in CI or Linux containers: puppeteer.launch({headless: true}).
• If you need a visible browser, start the script through xvfb-run or provide a real display server.

Minimal guard

try {
  // Run the Puppeteer operation that triggers this error.
} catch (error) {
  if (error instanceof Error && error.message.includes("Missing X server to start the headful br")) {
    // Apply the fix above, then retry or fail with a clearer message.
  }
  throw error;
}