How to Fix Puppeteer Screenshot Tests Failing on an Ubuntu Server in India

First identify whether Chrome fails to launch or the browser captures an image that later fails comparison. Those are different problems and need different fixes. Puppeteer’s reviewed documentation does not identify an India-specific failure mode; investigate location only if your server’s locale, timezone, fonts, or network access is demonstrably part of the failure.

Before changing flags or updating screenshot baselines, save the full error and record where the test stops: launch, navigation, screenshot capture, or image comparison. The steps below help isolate the cause while keeping browser versions and test conditions repeatable.

#	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.

What to record before changing anything

Keep the failing run’s complete output, including browser logs, and note:

• The exact test command and whether it runs locally, in CI, or inside a container.
• The installed Puppeteer version and the browser version it expects or launches.
• Ubuntu release, CPU architecture, Node.js version, and the operating-system user running the test.
• The Puppeteer install command and package manager, including whether install scripts are enabled.
• Launch flags, writable directory mounts, and any configured browser cache or profile path.
• The screenshot viewport, device emulation, capture mode, format, and relevant screenshot options.

Puppeteer’s system-requirements page, showing version 25.12.0 when accessed on October 3, 2026, lists Node.js 22.12 or later and Chrome for Testing support on Debian/Ubuntu x64 and arm64. Check the requirements for your installed Puppeteer release before upgrading an established application: Puppeteer system requirements.

#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

If Chrome fails before the screenshot

Check that the compatible browser was installed

Puppeteer normally downloads a compatible Chrome for Testing browser. Since Puppeteer v21.6.0, installation also downloads chrome-headless-shell; since v19.0.0, the default browser cache is $HOME/.cache/puppeteer. A package manager or deployment process that blocks install scripts can leave the expected browser unavailable.

Compare the build/install user with the test runtime user. They need access to the same cache, or you must install the browser at a location configured for the runtime. Puppeteer documents installing browsers with npx puppeteer browsers install and configuring the cache directory. Follow the instructions for your installed release: Puppeteer installation.

Look for missing shared libraries

If Chrome exists but exits immediately, inspect its library dependencies. Puppeteer’s troubleshooting guide recommends running ldd on the Chrome binary and looking for missing entries:

ldd /path/to/chrome | grep not

The path must point to the binary your test actually launches. Common Debian/Ubuntu dependencies include certificates, fontconfig, GBM, GTK, NSS, Pango, and X11 libraries. Package names can vary by Ubuntu release and browser build, so consult Puppeteer’s current troubleshooting guidance and its linked Chromium Debian dependency list rather than copying an old package-install command: Puppeteer troubleshooting.

The browser installer’s installDeps option can install Chrome dependencies on Debian or Ubuntu, but it requires system privileges to run apt-get. Use it only when your provisioning process is intended to grant those privileges: Puppeteer InstallOptions.

If the error mentions the Chrome sandbox

Do not add --no-sandbox as a reflex. Puppeteer warns: “Running without a sandbox is strongly discouraged.” Chrome’s sandbox is a security boundary, particularly important when tests visit untrusted pages.

On Ubuntu 23.10 and later, AppArmor policy can prevent Puppeteer-downloaded Chrome for Testing from using user namespaces, leading to errors such as No usable sandbox!. Check the host’s AppArmor policy and the location of the browser against Puppeteer’s troubleshooting guidance. Prefer correcting the host policy or browser configuration so Chrome can run sandboxed; do not disable sandboxing by default on a public-facing or untrusted-page runner. The documented issue and Chromium guidance are linked from Puppeteer troubleshooting.

If the screenshot is captured but its visual test fails

Use a matched browser build

Puppeteer is tightly bundled with a specific browser release to preserve protocol compatibility. Use the same Puppeteer/browser pair when generating baselines and running CI; do not assume that an arbitrary system Chrome is interchangeable. See Puppeteer’s FAQ.

Normalize viewport and capture options

Set the same viewport and device emulation in both environments. Puppeteer documents an 800 × 600 default headless screen unless --window-size is specified. Also keep capture behavior consistent: full page versus clipped viewport, image format, and any options such as clip, captureBeyondViewport, omitBackground, and image quality.

const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800, deviceScaleFactor: 1 });
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'shot.png', type: 'png', fullPage: true });

This is a minimal example, not a guarantee that network idle means the page is visually ready: applications can load content after that event. Wait for the application-specific element or state your test needs before capturing. Review the supported settings in Page.screenshot(), ScreenshotOptions, and Screen configuration.

Check fonts and loaded assets

Different installed fonts can change line breaks, glyphs, and element heights, creating widespread visual diffs. Puppeteer’s Linux guidance includes fonts-liberation among dependencies and notes that some character sets may need additional font files. Install the same fonts in baseline and CI environments based on the site’s actual scripts and CSS font stack; India alone does not establish which language fonts are needed.

Keep page state deterministic

Make the page content, data, animations, and asset availability consistent between baseline generation and CI. If the failure correlates with the server’s locale or timezone, set those conditions explicitly in both environments; otherwise, do not change them as a speculative India-specific fix.

If Chrome cannot write its profile or cache

Chrome writes profile, configuration, and cache files during startup. A read-only container or a restricted mount can make launch fail before Puppeteer connects. Give the runtime user a writable location and, if needed, set Puppeteer’s userDataDir to it. In containers, check that the mounted directory is writable and owned by the user running Chrome. Puppeteer documents this failure mode in its troubleshooting guide.

Rerun narrowly and change one condition at a time

1. Fix the cause that matches the failure stage: browser install, missing library, sandbox policy, permissions, or visual inconsistency.
2. Run one failing screenshot test and retain its browser logs and output image.
3. Compare the resulting environment and image with the baseline before changing expected screenshots.
4. Once the single test is stable, run the relevant suite in the same CI or container configuration.

Updating baselines before checking browser, fonts, assets, and viewport can conceal an environment regression rather than fix it.

Or skip the browser setup

If your goal is to capture a page rather than maintain a local Puppeteer runner, ScreenshotNeo provides a screenshot API and MCP server. A single request can return an image or PDF; the API also supports options such as full-page capture and viewport settings. The API parameters and request details are in the ScreenshotNeo documentation.

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

ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup 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 offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.

Sign up for 1,000 free screenshots a month, with no card required.

Frequently Asked Questions

Does an Ubuntu server in India need a special Puppeteer fix?

Not based on the reviewed Puppeteer documentation. Treat location as context unless you can reproduce a failure tied to locale, timezone, fonts, or network access.

Should I disable Chrome’s sandbox to make screenshot tests run?

No. Diagnose the sandbox error and host policy first; Puppeteer strongly discourages running without the sandbox.

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.

ChromeCINode.jsPuppeteerscreenshot testingUbuntu