How to Fix Puppeteer Hangs on Raspberry Pi Zero

A Puppeteer “hang” on a Raspberry Pi Zero is a symptom, not a diagnosis. The process may be stuck launching Chromium, waiting for navigation, waiting for a selector, or exhausting the board’s limited CPU and memory. First identify exactly where it stops and which Zero model you have; then test the browser independently before changing timeouts or automation code.

This guide gives a repeatable diagnostic path for the original Zero, Zero W/WH and Zero 2 W. It does not assume that one flag fixes every installation.

#	Preview	Product	Price
1		SANOOV Raspberry Pi Zero 2W Kit	$111.99	Buy on Amazon
2		CanaKit Raspberry Pi 4 4GB Starter PRO Kit - 4GB RAM	$159.99	Buy on Amazon

1. Identify the board and the exact point of failure

“Raspberry Pi Zero” can mean materially different hardware. The original Zero and Zero W/WH use a single-core 32-bit Arm v6 BCM2835 with 512 MB RAM. Zero 2 W keeps the same form factor but uses a quad-core 64-bit Cortex-A53 and also has 512 MB RAM. Raspberry Pi’s April 2024 product brief reports 40% more single-threaded and five times more multi-threaded performance for Zero 2 W compared with the original; those are vendor comparisons, not Puppeteer benchmarks or a promise that an upgrade cures a hang.

Record the environment

Before changing packages or launch flags, save the information below. Run commands as the same user that runs your Node process:

#1 Best Overall

SANOOV Raspberry Pi Zero 2W Kit

• Powerful Performance: Equipped with a quad-core 64-bit ARM Cortex-A53 processor, the Raspberry Pi Zero 2 W delivers a significant performance boost compared to its predecessor. And built-in Wi-Fi and Bluetooth support enable easy wireless communication and Internet access for your projects, five Times Faster.
• SANOOV Basic Starter Kit for Pi Zero 2 W Include: 1. Raspberry Pi Zero 2 W Board 2.Mini HDMI to Standard HDMI adapter 3.Micro-USB to Standard USB OTG Adapter 4.Aluminum Heatsink 5.40 Pin Header.NOTICE: The kit does NOT include , supply power, case, SD card, keyboard, mouse or monitor.
• SANOOV for Raspberry Pi Zero 2 W features: 1GHz quad-core, 64-bit ARM Cortex-A53 CPU VideoCore IV GPU 512MB LPDDR2 DRAM 802.11b/g/n wireless LAN Bluetooth 4.2 / Bluetooth Low Energy (BLE) MicroSD card slot Mini HDMI and USB 2.0 OTG ports Micro USB power HAT-compatible 40-pin header Composite video and reset pins via solder test points CSI camera connector.
• Video Output & Efficient Cooling: Supports 1080p30 video output via the mini HDMI port, making it ideal for multimedia applications and streaming.The aluminum heatsink helps dissipate heat, ensuring stable performance even under heavy workloads.
• Compact Size: The tiny size of the Raspberry Pi Zero 2 W makes it perfect for space-constrained projects and embedded applications.Ideal for a variety of uses, including IoT projects, home automation, media centers, educational tools, and more.

$111.99

Buy on Amazon

cat /proc/device-tree/model; echo
getconf LONG_BIT
uname -m
cat /etc/os-release
node --version
npm list puppeteer puppeteer-core --depth=0
which chromium chromium-browser google-chrome 2>/dev/null || true

Also record the browser version and path you intend to use, your complete puppeteer.launch() call, all command-line arguments, and the full standard error output. Note whether the stall occurs at browser launch, page.goto(), a selector wait, a script evaluation, or after the page appears.

Use a minimal reproduction

Remove application code and test one operation at a time. This distinguishes a non-starting browser from a page or DevTools-protocol wait:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    dumpio: true,
    timeout: 30000
  });
  console.log('browser launched');
  const page = await browser.newPage();
  await page.goto('https://example.com', {
    waitUntil: 'domcontentloaded',
    timeout: 30000
  });
  console.log('navigation finished:', await page.title());
  await browser.close();
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

If “browser launched” never prints, debug the executable and its dependencies. If launch succeeds but navigation waits, investigate DNS, TLS, network access and the selected waitUntil condition. If navigation finishes but your real script waits, inspect selectors, page JavaScript and API calls.

2. Verify the browser Puppeteer is actually starting

Puppeteer normally downloads a browser revision intended for that Puppeteer release. A system browser is a different arrangement: you must provide its executable path and verify that its version is compatible with your Puppeteer package. Do not copy an x86-64 binary to an Arm board. The original Zero’s Arm v6 architecture is especially restrictive; a current Chrome for Testing build is not promised for it by official pages.

Print and test the executable path

For a system browser, make the path explicit:

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/chromium',
  headless: true,
  dumpio: true,
  timeout: 30000
});

Replace the path with the result of which. Run that executable directly, as the service account or login user that runs Puppeteer:

/usr/bin/chromium --version
/usr/bin/chromium --headless --no-first-run --disable-gpu about:blank

The direct command should either exit cleanly or produce a clear startup error. If it stalls or exits immediately, Puppeteer is not yet the problem.

Check architecture, libraries and permissions

Confirm the file type and dynamic dependencies:

file /usr/bin/chromium
ldd /usr/bin/chromium

Look for an architecture mismatch, “not found” shared libraries, denied execution, or a profile directory that the account cannot write. Puppeteer’s Linux troubleshooting guidance specifically recommends checking dependencies with ldd <browser-path>. Its example package list targets common Debian/Ubuntu systems; package names and availability must be checked against the Raspberry Pi OS release and architecture you actually installed.

Use the distribution’s supported browser package rather than forcing an unrelated binary. If you change the browser, re-run the direct launch test and the minimal Node script before restoring your full workload.

3. Separate launch failures from page waits

A longer timeout only changes how long Puppeteer waits; it cannot repair an incompatible executable or a browser that never starts. Set an explicit, finite timeout for each operation while diagnosing:

page.setDefaultTimeout(15000);
page.setDefaultNavigationTimeout(30000);
await page.goto(target, { waitUntil: 'domcontentloaded', timeout: 30000 });

Navigation that never completes

waitUntil: 'networkidle0' can wait indefinitely in practical terms on pages that keep analytics, WebSocket or polling connections open. Start with domcontentloaded, then wait for the one selector that proves the page is ready:

await page.goto(target, { waitUntil: 'domcontentloaded', timeout: 30000 });
await page.waitForSelector('#main-content', { timeout: 15000 });

Capture the URL, response status and console output so a network or page-script problem is not mistaken for a browser hang:

page.on('console', message => console.log('PAGE', message.type(), message.text()));
page.on('pageerror', error => console.error('PAGE ERROR', error));
page.on('requestfailed', request => console.error('REQUEST FAILED', request.url(), request.failure()));
page.on('response', response => {
  if (response.status() >= 400) console.error('HTTP', response.status(), response.url());
});

Selector or script waits

Check that the selector exists in the current frame and that the page did not redirect. Prefer a bounded wait and log the last known URL:

try {
  await page.waitForSelector('.result', { timeout: 15000 });
} catch (error) {
  console.error('wait failed at', page.url(), error.message);
  throw error;
}

For iframes, obtain the frame and query it there; a selector in the top document will never match an element inside a child frame. For application code that polls forever, add your own deadline around the operation instead of increasing Puppeteer’s global timeout.

Rank #2

CanaKit Raspberry Pi 4 4GB Starter PRO Kit - 4GB RAM

• Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
• Includes Pre-Loaded 32GB EVO+ Micro SD Card (Class 10), USB MicroSD Card Reader
• CanaKit Premium High-Gloss Raspberry Pi 4 Case with Integrated Fan Mount, CanaKit Low Noise Bearing System Fan
• CanaKit 3.5A USB-C Raspberry Pi 4 Power Supply (US Plug) with Noise Filter, Set of Heat Sinks, Display Cable - 6 foot (Supports up to 4K60p)
• CanaKit USB-C PiSwitch (On/Off Power Switch for Raspberry Pi 4)

$159.99

Buy on Amazon

4. Measure CPU, memory and swap while reproducing

The original Zero has one CPU core and 512 MB RAM. Browser startup, JavaScript execution and image decoding can therefore contend with the operating system. That makes resource pressure plausible, but it is not proof of the cause on your board.

Observe the board during the hang

In another shell, watch processes and memory:

free -h
swapon --show
top
ps -o pid,ppid,%cpu,%mem,rss,stat,cmd -C node -C chromium

Record whether RAM is exhausted, swap is constantly active, one process consumes the only core, or the kernel reports an out-of-memory kill:

dmesg | tail -n 80

Do not infer a fixed “safe” memory threshold from another Pi. Compare your failing run with a minimal page, then reduce one load at a time: disable unnecessary tabs, avoid full-page screenshots, limit concurrent pages, block nonessential resources, and process URLs sequentially. Close each browser and page explicitly so orphaned Chromium processes do not accumulate.

Reduce the test workload

• Try a tiny static page before a JavaScript-heavy application.
• Use one page and one browser process; add concurrency only after the single case is stable.
• Set a finite navigation and selector timeout and log which one expires.
• Measure with and without images or other optional resources, rather than assuming they are the bottleneck.

5. Handle sandboxing safely

Do not blindly add --no-sandbox. Puppeteer’s troubleshooting documentation strongly discourages running without the sandbox because it weakens browser isolation. First fix executable, dependency, permission and account issues. Only consider a no-sandbox diagnostic or constrained workaround when you understand the deployment’s security context, the process is isolated appropriately, and the risk is acceptable:

const browser = await puppeteer.launch({
  headless: true,
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
  dumpio: true,
  timeout: 30000
});

If this changes the result, treat it as evidence of a sandbox or permission problem, not as a generally safe production setting. Revisit the user account, kernel support and browser packaging instead.

6. A disciplined recovery sequence

1. Identify the exact Zero model, OS release, bitness, Node version, Puppeteer version and browser path.
2. Run the browser executable directly under the production user and capture stderr.
3. Use file and ldd to find architecture or missing-library errors.
4. Run the minimal launch-and-domcontentloaded script with dumpio and finite timeouts.
5. Add console, page-error, failed-request and HTTP-status logging.
6. Measure CPU, RAM, swap and kernel messages during a reproduction.
7. Reduce pages, tabs, assets and concurrency; close resources after each job.
8. Only after measuring a CPU limitation on an original Zero, evaluate a Zero 2 W. It retains 512 MB RAM, and its official performance figures do not guarantee Puppeteer compatibility.

7. Common symptoms, causes and fixes

Or skip the browser setup

If your goal is a reliable website image rather than maintaining Chromium on a Pi, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.

See the parameter reference in the ScreenshotNeo documentation. This cURL call captures Stripe as WebP:

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

Equivalent Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Equivalent Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo supports full-page and element captures, device presets and custom viewports, retina scale, dark mode, PDF controls, custom CSS and JavaScript, clicks, waits, resource blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification. Its parameter names are compatible with those used by many screenshot APIs, which can simplify migration.

The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and annual billing gives two months free. Create a free ScreenshotNeo account to try it without a card.

FAQ

Does Zero 2 W guarantee that Puppeteer will work?

No. It is substantially faster by Raspberry Pi’s published comparison, but it still has 512 MB RAM and browser support depends on the OS, architecture and executable you install.

Should I always set timeout: 0?

No. An infinite timeout hides the failing operation and can leave a constrained board stuck forever. Use finite, operation-specific limits while collecting diagnostics.

What information should I include when asking for help?

Provide the exact board model, OS and bitness, Node and Puppeteer versions, browser path and version, launch arguments, complete stderr, the operation that waits, and CPU/memory observations from the failing run.

Frequently Asked Questions

Can a cache hit still consume a ScreenshotNeo shot?

No. ScreenshotNeo states that cache hits are not billed, and the response identifies the billing result in its headers.

Can I capture only one element instead of a whole page?

Yes. ScreenshotNeo supports selecting one element by CSS selector as well as full-page capture.

Quick Recap

Bestseller No. 1

SANOOV Raspberry Pi Zero 2W Kit

$111.99

Bestseller No. 2

CanaKit Raspberry Pi 4 4GB Starter PRO Kit - 4GB RAM

Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM); Includes Pre-Loaded 32GB EVO+ Micro SD Card (Class 10), USB MicroSD Card Reader

$159.99

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.