Puppeteer Screenshot Is Blank on Ubuntu Server: Troubleshooting

A blank Puppeteer screenshot is a symptom, not a diagnosis. First verify that Chrome reached the expected page and that its content was ready; then check the Ubuntu browser runtime, sandbox, capture settings, and saved image. A resolved page.goto() call alone does not prove that the expected content appeared.

1. Find out what Puppeteer actually loaded

Before changing packages or browser flags, log the final URL, navigation response, title, and a small amount of page content. Puppeteer’s Page.goto() API resolves with the main-resource response; after redirects, that is the response for the last redirect. It can return null for about:blank and same-document hash navigation. Headless shell also does not reject valid HTTP statuses such as 404 or 500, so inspect the status when a response exists.

#	Preview	Product	Price
1		GEEKOM Air12 Budget Mini PC Office,Intel 7505,8GB RAM(64GB Max),256GB SSD	$499.00	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

const response = await page.goto(targetUrl, { waitUntil: 'domcontentloaded' });

console.log({
  requestedUrl: targetUrl,
  finalUrl: page.url(),
  status: response?.status() ?? null,
  title: await page.title(),
  body: (await page.locator('body').textContent().catch(() => ''))?.slice(0, 500),
});

Also check the expected page-specific selector, browser console errors, and failed requests. A capture may faithfully show a login page, bot challenge, proxy response, browser warning, or error page rather than a white page. For remote HTTP targets, Chrome for Testing may show an HTTP-first warning interstitial; Puppeteer documents that some navigations can result in net::ERR_BLOCKED_BY_CLIENT. Inspect the final URL and visible content before treating that as an Ubuntu rendering failure (Puppeteer troubleshooting).

2. Wait for the page’s actual ready condition

Navigation lifecycle events describe browser activity, not whether a client-rendered application has finished populating the content you need. Wait for a meaningful selector or application-specific state before capturing:

#1 Best Overall

GEEKOM Air12 Budget Mini PC Office,Intel 7505,8GB RAM(64GB Max),256GB SSD

• ➊ [ Trusted Quality for Everyday Agentic AI ] GEEKOM equips its SSDs with reliable original-grade flash and conducts rigorous stability testing to support dependable everyday operation. This commitment to quality is backed by a 3-year warranty. Simply connect the Air12 to cloud AI services for research, writing, study support and daily productivity—no NPU or complex local setup required. Designed for students, home users, light office work and first-time buyers, the Air12 is a high-value Cloud Agentic PC for everyday tasks
• ➋ [ Intel 7505 processor ] Powered by the Intel 7505 processor (2 cores, 4 threads, up to 3.5GHz), the GEEKOM Mini PC Air12 delivers smooth performance for everyday computing, office tasks, and home entertainment. With enhanced single-core processing, it handles daily workloads efficiently and responsively. Compact, quiet, and energy-efficient — a solid alternative to bulky desktops.
• ➌ [440lbs(200kg) Pressure Rated Metal Frame for Demanding Environments] Unlike the Plastic Shells You’ll Find on Most Mini PCs, geekom Mini Air12 features a triple-reinforced ABS+PC shell, precision-crafted metal frame and baseplate—engineered to withstand up to 440 lbs of pressure for the perfect balance of strength and thermal efficiency. Tool-free upgrades, shock-absorbing feet, and a 3D antenna deliver true durability
• ➍ [Dual-Channel RAM & NVMe SSD Expandability] Ships with 8GB DDR4 RAM and a 256GB NVMe SSD for smooth everyday performance. Dual memory slots and dual storage slots give you the flexibility to upgrade to 64GB RAM and 2TB SSD, so your system can adapt as your workload grows. Enjoy faster load times, smoother multitasking, and long-term reliability.
• ➎ [Triple 4K Displays for Maximum Productivity] Connect up to three 4K monitors via HDMI 2.0, Mini DisplayPort 1.4, and USB-C — ideal for stock trading dashboards, multi-tab research, office document editing, and light spreadsheet work. WiFi 6 and Bluetooth with high-gain antenna ensure stable wireless connections throughout your workspace. 5x USB ports and a full-size SD card reader provide quick access to peripherals and camera files — no adapters required.

$499.00

Buy on Amazon

await page.goto(targetUrl, { waitUntil: 'domcontentloaded' });
await page.waitForSelector('[data-page-ready="true"]', { timeout: 15000 });
await page.screenshot({ path: 'shot.png' });

Replace the selector with one that indicates the target content is genuinely available. If the page has no useful marker, use a condition that reflects the content you need, such as waiting for a known heading to contain text. waitForNetworkIdle() can help when the page’s request pattern makes network idleness meaningful; it always waits at least its configured idle time, but it is not proof that visual work or application logic is finished.

For diagnosis, compare the page text, selector state, console errors, failed requests, and screenshot after the selector appears with the same evidence after an appropriate network-idle wait. Avoid treating an arbitrary fixed delay as a dependable fix.

3. Verify the deployed browser and runtime

Record the Node.js version, Puppeteer package and version, browser version, and actual executable path in the Ubuntu environment where the job runs. Local development and a VPS or CI worker may have different browser installations or launch behavior.

• puppeteer downloads a compatible Chrome for Testing by default. If deployment tooling blocks package install scripts, that download may be skipped; Puppeteer’s installation guide describes installing browsers explicitly with npx puppeteer browsers install or allowing the install script.
• puppeteer-core does not download Chrome. If you use it, manage the browser yourself and provide an executable path or channel.
• The current system requirements list Node 22.12+ and Debian/Ubuntu x64 and arm64 for Chrome for Testing. Treat these as version-sensitive requirements and check them against the installed Puppeteer and browser.

A minimal local HTML page is a useful split test. If it renders in the same process, the browser can launch and capture a basic page; investigate target-specific scripts, resources, authentication, or access controls next. That narrows the search but does not by itself identify the cause.

4. Check Ubuntu libraries and fonts

Run the dependency check against the actual Chrome binary used by Puppeteer:

ldd /path/to/chrome | grep not

Use the reported missing libraries and the current browser build to guide package installation. Puppeteer’s Linux troubleshooting guide lists Debian/Ubuntu dependencies including libnss3, libgbm1, GTK, Pango, X11-related libraries, and fonts-liberation; the current Chrome installer package manifest is the up-to-date reference for the browser’s package list. Do not assume an older blog’s package list still matches your binary.

Missing fonts are worth checking when glyphs are absent or text looks wrong, but they are a weaker explanation for an entirely blank page unless the observed symptoms point to fonts.

5. Diagnose sandbox and AppArmor errors separately

Chrome’s Linux sandbox isolates web content. If Chrome reports No usable sandbox!, investigate the host’s sandbox configuration rather than treating it as a generic screenshot issue. Puppeteer documents a specific Ubuntu 23.10+ AppArmor interaction: an AppArmor profile associated with Chrome stable at /opt/google/chrome/chrome can prevent Puppeteer-downloaded Chrome for Testing binaries from using user namespaces.

Check the Ubuntu release, the browser binary path, and current upstream AppArmor guidance before selecting a workaround. Puppeteer’s warning is explicit: “Running without a sandbox is strongly discouraged. Consider configuring a sandbox instead.” Do not make --no-sandbox a routine production fix. At most, use it as a narrowly scoped diagnostic on trusted content, understanding that it reduces browser isolation (Puppeteer troubleshooting).

6. Inspect viewport, screenshot options, and file handling

An image can look blank or incomplete even when the page rendered. Check the configured viewport and any clip rectangle, then verify the capture options and output code against Puppeteer’s ScreenshotOptions API and Page.screenshot() API.

• fullPage defaults to false. Set it to true if you need the full document rather than the viewport.
• captureBeyondViewport defaults to false when there is no clip. A clip or unexpected viewport may exclude the content you meant to capture.
• omitBackground defaults to false; transparency settings can change how an image appears in a viewer.
• The default format is PNG. Screenshot output is a Uint8Array by default; if base64 encoding is configured, decode it as base64 rather than writing the string as binary image data.
• An output path is optional. If you supply one, confirm the process can write there and that the file you inspect is the newly generated file.

const image = await page.screenshot({ path: 'shot.png', fullPage: true });
console.log({ bytes: image.length });

Reopen the result with a known image viewer and check its file type and dimensions. Avoid racing capture against code that changes or closes the page: screenshot operations coordinate with selected page-opening and closing methods, while Page.bringToFront() does not wait for an existing screenshot operation.

7. Separate headless capture from display-server problems

Puppeteer runs headless by default; a physical monitor is not required for ordinary headless capture. If your code explicitly sets headless: false, a non-graphical server may need a display server such as Xvfb. That is a separate branch to investigate, not a general remedy for an empty headless screenshot (Puppeteer headless modes).

Quick diagnostic order

1. Record Node, Puppeteer, browser versions, and the executable path.
2. Log the final page.url(), navigation response and status, title, body text, and an expected selector.
3. Check redirects, console errors, failed requests, error or interstitial content, and any authentication or rendering requirements.
4. Wait for page-specific readiness; use network idle only when appropriate.
5. Run ldd on the actual browser binary and install only confirmed missing dependencies using current package guidance.
6. If you see No usable sandbox!, investigate the host sandbox and Ubuntu/AppArmor path; do not reflexively disable the sandbox.
7. Check viewport, clipping, full-page capture, background, encoding, output path, and the saved file.
8. Capture a minimal local page to distinguish basic browser launch/rendering from target-specific behavior.

Or skip the browser setup

If you need a screenshot without maintaining a Puppeteer browser on the Ubuntu host, ScreenshotNeo takes a URL in one API request and returns an image or PDF. It accepts cookie banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.

For the API key and all request options, see the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

Quick Recap

Bestseller No. 1

GEEKOM Air12 Budget Mini PC Office,Intel 7505,8GB RAM(64GB Max),256GB SSD

$499.00

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.