The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →If Puppeteer’s screenshot fails in Docker, first identify whether Chrome is missing Linux libraries, the browser executable is missing, the sandbox cannot start, or Chrome cannot write its profile and cache. Each failure needs a different fix. This guide follows the current Puppeteer 25.12.0 documentation; its system requirements specify Node.js 22.12 or later. Check package names against your exact Linux distribution and version before changing the image.
Identify which Chrome startup failure you have
Read the complete Docker build and runtime logs, then match the error to the failure class. Chrome can be installed but unable to load a shared library; a library fix will not solve a missing browser executable, and neither addresses a sandbox or filesystem problem. Puppeteer’s troubleshooting guide documents these separate causes.
| Symptom | Likely cause | First check |
|---|---|---|
| Chrome exits before Puppeteer connects; an error names a missing shared library | Required Linux libraries are absent | Run ldd against the Chrome executable inside the built image |
Could not find expected browser locally or executable ENOENT |
Browser download did not run, cache paths differ, or the executable path is wrong | Check the installed package, build logs, cache location, and configured executable |
No usable sandbox! |
Chrome cannot use its sandbox in the container’s runtime configuration | Check the container capabilities and sandbox setup |
chrome_crashpad_handler: --database is required or profile/cache startup failure |
Chrome cannot write to its configuration, cache, or user-data directory | Check writable paths and directory ownership |
Fix missing shared libraries in a custom image
Run the dependency check against Chrome inside the same image that fails at runtime. Find the executable path first if chrome is not on PATH; use the path reported by Puppeteer or the browser installation. Then inspect unresolved dependencies:
ldd /path/to/chrome | grep notFor example, if the executable is available as chrome on PATH, use:
#1 Best Overall
- The Anker Advantage: Join the 80 million+ powered by our leading technology.
- Vivid Video: The HDMI adapter lets you connect to any TV or display with an HDMI port to stream video in up to 4K resolution.
- Plug and Play: Instantly turn your laptop’s USB-C port into an HDMI port, with no installation necessary. This product does not support charging or Power Delivery (PD).
- Premium Construction: A lightweight aluminum casing allows for greater heat dissipation, while the reinforced braided-nylon cable is designed to withstand the twists and tugs of daily use.
- Compatibility: Supports USB-C DP Alt mode, USB4, and Thunderbolt connections.
ldd "$(command -v chrome)" | grep notInstall the packages that provide the reported libraries using the package manager and repositories for your base image. Puppeteer’s troubleshooting page lists common Debian/Ubuntu dependencies, including GTK, NSS, GBM, X11, and font libraries, as well as a separate CentOS package set. Those lists are starting points, not universal recipes: package names and requirements depend on distribution and version. Use the current Puppeteer system requirements and the relevant distribution’s Chromium package manifest rather than copying an old package list blindly.
Rebuild the image and repeat the dependency check in the rebuilt container. If ldd reports no unresolved libraries but launch still fails, investigate the browser path, sandbox, and writable directories instead of adding unrelated packages.
Fix a missing browser executable or download
The error Could not find expected browser locally or an executable ENOENT points to the browser installation or path, not necessarily to missing shared libraries. Puppeteer’s installation guide says installing puppeteer downloads Chrome for Testing and, starting with Puppeteer 21.6.0, chrome-headless-shell. By contrast, puppeteer-core does not download a browser for you.
Rank #2
![BENFEI USB C to HDMI Adapter 4K@60Hz, USB Type-C to HDMI Adapter [Thunderbolt 3/4/5 Compatible] with iPhone 15 Pro/Max, MacBook Pro/Air 2023, iPad Pro, iMac, S23, XPS 17, Surface Book](https://m.media-amazon.com/images/I/31kTmzsrThL._SL160_.jpg)
- COMPACT DESIGN - The compact-designed portable BENFEI USB-C to HDMI adapter connects a computer, desktop, laptop, or other devices with USB-C port to a monitor, projector, HDTV, or other devices with HDMI port; Tuck this lightweight gadget into your bag or pocket to do a business presentation with your laptop and projector, or extend your desktop screen to a monitor or TV;
- SUPERIOR STABILITY - Built-in advanced IC chip converts USB-C digital signal to HDMI signal; Please pay attention, the USB-C device should support the USB Type-C DP Alt mode.
- INCREDIBLE PERFORMANCE - The USB-C to HDMI adapter supports resolutions up to 3840*2160@60Hz including, 3840*2160@30Hz, 2K@144Hz, 1080P, 720p, 1600x1200, 1280x1024 for high definition monitors or projectors; Plated USB-C connector resists corrosion and abrasion and improve the signal transmission performance; Molded strain relief increases cable durability
- BROAD COMPATIBILITY - The BENFEI USB-C to HDMI is compatible with iPhone 15 Pro/Max, 13"/15" MacBook Pro/Air, iMac,2023,2022,2021, 2020, 2019, Google Chromebook Pixel, Yoga 900, Dell XPS 13 (9350), Dell XPS 15 9550, Dell XPS12 9250, DellPrecision 5510, HP Spectre X2, HP Spectre x360, HP Elitebook Folio G1, HP Elite x2 1012 G1, Acer Switch Alpha 1, Acer Spin 7, Acer Chromebook R13, Samsung Chromebook Plus, Samsung Galaxy TabPro S,Samsung Galaxy A7 2017, LG G5, LG V20, HTC 10
- 18 MONTH WARRANTY - Exclusive BENFEI Unconditional 18-month Warranty ensures long-time satisfaction of your purchase; Friendly and easy-to-reach customer service to solve your problems timely Compare with similar items
- Confirm the image build actually ran the Puppeteer browser-install step. Some package-manager configurations block dependency install scripts, so a successful package install alone does not prove Chrome was downloaded.
- Check that the build and runtime use the same home directory and cache location. Puppeteer’s default browser cache has been
~/.cache/puppeteersince v19.0.0; setPUPPETEER_CACHE_DIRif your build or deployment needs a different location. - If browser download was intentionally skipped, install a compatible system browser and configure Puppeteer to launch that executable consistently. Do not assume that the browser path on the host is available inside the container.
- Keep Puppeteer and its browser aligned when changing versions. Puppeteer v20.0.0 moved to Chrome for Testing, according to its supported-browsers documentation.
For reproducible builds, pin a deliberate Puppeteer and browser-image version, and verify the install step and executable path after upgrades.
Resolve sandbox errors without making no-sandbox the default
Puppeteer strongly discourages running Chrome without its sandbox. If the error is No usable sandbox!, first use a container setup that supports the sandbox rather than treating --no-sandbox as a routine workaround.
The official Puppeteer Docker guide documents running its image with --cap-add=SYS_ADMIN for sandboxing and recommends --init or a custom init entrypoint to manage browser child processes. If a constrained environment leaves no alternative to disabling the sandbox, understand that this weakens isolation and restrict it to trusted content; it is not a general-purpose fix for missing libraries.
Rank #3
- CHECK YOUR DEVICE FIRST( USB-C MALE TO HDMI FEMALE): This adapter works with USB Type C ports that support DP Alt Mode. Want to be sure before you buy? Check your device specs - not every USB-C port sends video.
- ONE-WAY VIDEO & AUDIO OUTPUT: This adapter sends video and audio from your USB-C device to an HDMI display. It does not support charging, and it is not designed for HDMI-to-USB-C direction.
- 4K@60Hz USB-C TO HDMI ADAPTER CABLE: Get clear 4K picture at 60Hz from a compatible USB-C laptop or tablet. It also works with older HDMI 1.4, 1.3 and 1.2 screens.
- PLUG AND PLAY, NO SETUP: Turn your USB-C port into an HDMI port with no drivers and no installation. What you see depends on your device and your screen.
- EXTEND YOUR REACH: Going from USB-C male to HDMI female lets you keep using the HDMI cable you already have, and place your laptop or phone where you want it.
Make Chrome’s profile and cache writable
Chrome writes configuration, cache, and user-data files during startup. A read-only filesystem, a directory owned by a different user, or a cache path unavailable at runtime can therefore stop Chrome even when its libraries and executable are present.
- Set
XDG_CONFIG_HOMEandXDG_CACHE_HOMEto directories that exist and are writable by the container’s browser user. - Set Puppeteer’s
userDataDirto a writable location, or mount a writable volume for the profile when persistence is needed. - For ephemeral runtime files, use writable
/tmppaths where appropriate, and ensure the runtime user owns mounted directories.
The crashpad error chrome_crashpad_handler: --database is required can be a clue that Chrome’s expected profile or database location is unavailable. Check the paths and permissions before changing browser flags.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose a Docker image strategy
Custom base image
A custom image gives you control over the distribution, installed packages, and application layout. In return, you must maintain the Linux libraries Chrome needs, ensure the browser version matches Puppeteer, provide writable runtime paths, and manage Chrome’s child processes. Tie package names to the base distribution and version; do not use a historical Dockerfile as a current drop-in build recipe.
Rank #4
- 【4K UHD Visual Feast】This USB-C to HDMI cable supports up to 4K@60Hz resolution and is backward compatible with 1440P@60Hz and 1080P@120Hz. It can seamlessly transmit at 3840x2160 resolution, providing crystal-clear images and smooth video, suitable for high-definition monitors, TVs, and projectors, meeting the needs of various devices and use cases. 📌𝐍𝐨𝐭𝐞: 𝐔𝐒𝐁-𝐂 𝐩𝐨𝐫𝐭 𝐦𝐮𝐬𝐭 𝐬𝐮𝐩𝐩𝐨𝐫𝐭 "𝐃𝐢𝐬𝐩𝐥𝐚𝐲𝐏𝐨𝐫𝐭 𝐀𝐥𝐭𝐞𝐫𝐧𝐚𝐭𝐞 𝐌𝐨𝐝𝐞". 𝐍𝐎𝐓 𝐬𝐮𝐩𝐩𝐨𝐫𝐭 𝐏𝐨𝐫𝐭𝐚𝐛𝐥𝐞 𝐌𝐨𝐧𝐢𝐭𝐨𝐫 𝐨𝐫 𝐔𝐥𝐭𝐫𝐚 𝐖𝐢𝐝𝐞 𝐌𝐨𝐧𝐢𝐭𝐨𝐫.
- 【Plug-and-Play Simplicity】This Thunderbolt 3 to HDMI connects from your Type-C phone, tablet, laptop, and desktop computer to larger displays like monitor, TV, and projector. Leave behind the worries of unstable WiFi and the hassle of drivers. HDCP compliance ensures smooth media streaming without limitations. 📌𝐍𝐨𝐭𝐞: 𝐨𝐧𝐞-𝐰𝐚𝐲 𝐜𝐨𝐫𝐝, 𝐞𝐱𝐜𝐥𝐮𝐬𝐢𝐯𝐞𝐥𝐲 𝐟𝐫𝐨𝐦 𝐔𝐒𝐁-𝐂 𝐡𝐨𝐬𝐭 𝐝𝐞𝐯𝐢𝐜𝐞𝐬 𝐭𝐨 𝐇𝐃𝐌𝐈 𝐝𝐢𝐬𝐩𝐥𝐚𝐲𝐬
- 【Sturdy and Lasting Design】Braided cable for enhanced durability and resistance to wear and tear. Reinforced connectors prevent loosening or breaking after repeated use. Premium aluminum or copper shielding provides better heat dissipation and prevents signal loss. The usbc to hdmi ensures synchronized video and audio with no lag or interruptions, perfect for gaming, movies, or presentations. *Note: Only supports Android phones with video output function. Not support iPhone Lightning. Does not support HDR.
- 【Improve Work Efficiency】 Mirror or Extend your desktop to boost productivity. Connect to a 4K LED monitor or UHD TV. This c to hdmi cable meets all the smooth, lag-free work, meetings, or multimedia needs. Multiple length options (e.g., 3.3FT, 6.6FT, 10FT) for different setups, from office desks to living rooms. 📌𝐍𝐨𝐭𝐞: 𝐓𝐡𝐞 𝐜𝐚𝐛𝐥𝐞 𝐝𝐨𝐞𝐬 𝐧𝐨𝐭 𝐡𝐚𝐯𝐞 𝐚 𝐩𝐨𝐰𝐞𝐫 𝐬𝐮𝐩𝐩𝐥𝐲, 𝐬𝐨 𝐢𝐭 𝐜𝐚𝐧 𝐧𝐨𝐭 𝐜𝐡𝐚𝐫𝐠𝐞 𝐲𝐨𝐮𝐫 𝐝𝐞𝐯𝐢𝐜𝐞.
- 【Universal Compatibility】The Thunderbolt 3/4/5 to HDMI cable works seamlessly with USB-C devices that support DisplayPort Alternate Mode (DP Alt Mode) for video output; Compatible with MacBook Neo, Pro 2016-2024, MacBook Air 2018-2024, iMac (2017 and later), iPad Pro (2021 and later), iPad Air (2021 and later), iPhone 16/ 15 Pro Max/ 15 Pro/ 15 Plus, Mac Studio, Mac Pro, Surface Book 2/3, Surface Laptop 3, Dell XPS 15/13, HP Chromebook x360, Samsung Galaxy S24/S23/S22/S21/S20/S10/S9/S8, Note 20/10/9/8, LG V40, Steam Deck, and more. 📌𝐍𝐨𝐭 𝐒𝐮𝐩𝐩𝐨𝐫𝐭 𝐃𝐨𝐜𝐤/ 𝐃𝐨𝐜𝐤𝐢𝐧𝐠/ 𝐇𝐮𝐛/ 𝐌𝐨𝐭𝐨𝐫𝐨𝐥𝐚 𝐒𝐞𝐫𝐢𝐞𝐬.
Official Puppeteer image
The maintained ghcr.io/puppeteer/puppeteer image includes Chrome for Testing and its required dependencies. Puppeteer’s Docker guide documents latest and version-specific tags. Prefer a deliberate version tag when reproducibility matters, and update it alongside compatible Puppeteer versions. Its documented sandboxed invocation uses --cap-add=SYS_ADMIN and --init; adapt the application entrypoint and mounts to your deployment.
The official image reduces dependency assembly, but it does not remove the need to consider sandbox capabilities, process management, writable directories, or whether the image supports your target distribution and architecture. The current system requirements list Debian/Ubuntu and openSUSE/Fedora Linux on x64 and arm64 for Chrome for Testing. Do not assume an Ubuntu package list or Chrome setup works on Alpine.
Handle Alpine and headless GPU cases separately
Alpine Linux
Puppeteer says Chrome does not support Alpine out of the box. Alpine uses different packages and its Chromium/browser compatibility can change, so verify the precise Puppeteer, browser, and Alpine versions before relying on a workaround. The troubleshooting page mentions a timeout issue with the Chromium version in Alpine 3.20 and a reported fix using Alpine 3.19; treat that as version-specific guidance, not a standing guarantee for current images.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- [Effortless Plug & Play] Crystal-clear and vibrant 4K@60Hz resolution backward compatible for 1440P/2K@144Hz and 1080P@240Hz. Instantly mirror or extend UHD content from your Type-C phone, tablet, laptop, and desktop computer to larger displays like monitors, TVs, and projectors. Leave behind the worries of unstable WiFi and the hassle of drivers. HDCP compliance lets you enjoy media streaming without any limitations.𝗣𝗹𝗲𝗮𝘀𝗲 𝗡𝗼𝘁𝗲: 𝗧𝗵𝗶𝘀 𝗶𝘀 𝗮 𝗼𝗻𝗲-𝘄𝗮𝘆 𝗰𝗮𝗯𝗹𝗲, 𝗱𝗲𝘀𝗶𝗴𝗻𝗲𝗱 𝗲𝘅𝗰𝗹𝘂𝘀𝗶𝘃𝗲𝗹𝘆 𝗳𝗼𝗿 𝘁𝗿𝗮𝗻𝘀𝗺𝗶𝘀𝘀𝗶𝗼𝗻 𝗳𝗿𝗼𝗺 𝗨𝗦𝗕-𝗖 𝗵𝗼𝘀𝘁 𝗱𝗲𝘃𝗶𝗰𝗲𝘀 𝘁𝗼 𝗛𝗗𝗠𝗜 𝗱𝗶𝘀𝗽𝗹𝗮𝘆𝘀.
- [Exquisite Craftsmanship] Every detail is meticulously designed for excellence: The gold-plated connector ensures secure and high-speed data transmission, delivering interference-free performance. A modern upgrade over fragile Serial Cables and finicky wireless dongles — one slim cable delivers interference-free 4K with full HDCP compliance for unlimited media streaming.The uni-body molding ensures an unbreakable connection, while the aluminum case efficiently dissipates heat for extended usage. The thicker copper wire minimizes signal loss, providing maximum conductivity for an impeccable audio-visual experience.
- [Intricate Design] Elevate your experience with impeccable materials. The nylon braided cable jacket offers worry-free usage, eliminating concerns of fraying, heating, or kinking. The non-slip thumb grip provides a comfortable and secure plug-in experience. The streamlined metal pieces seamlessly connect, offering shock-proof reliability. Bonus Velcro tie adds convenience for travel. The stylish gray metallic case with a hint of blue embodies elegance and sophistication.
- [Extensive Compatibility] Designed for Type C ports with video output capability (DP Alt Mode) and Thunderbolt 3 & 4. Enjoy compatibility with a wide range of devices, including iPhone 15/16/17 Series, MacBook Neo, Apple MacBook Pro (2016 and later), iMac (2017 and later), MacBook Air (2018 and later), iPad Pro (2021 and later), Mac Studio, Mac Pro, Surface Book 2/3, Surface Laptop 3, Dell XPS 15/13, HP Chromebook x360, Samsung Galaxy S23/S22/S21/S20/S10/S9/S8, Note 20/10/9/8, LG V40, Steam Deck, and more.
- [WARRKY: Elevating Connections in Work and Life] Provides superb-quality products that harmonize sophistication and affordability, helping you enhance both your work and personal life. We are committed to delivering fast and responsive support within 18 hours. Please consult WARRKY anytime.
GPU acceleration in headless mode
This is relevant only when GPU acceleration is needed. Puppeteer’s troubleshooting guide says chrome-headless-shell needs --enable-gpu for GPU acceleration in headless mode. It is not a general fix for a browser that cannot launch or for a missing screenshot.
Use this verification sequence after a fix
- Build the image with the intended Puppeteer and browser versions, and confirm the browser installation step ran.
- Inspect the actual executable inside the built image. If launch fails with a library error, run
ldd /path/to/chrome | grep notand resolve missing libraries for that distribution. - Check runtime paths as the same user that launches Puppeteer. Confirm the browser cache, XDG directories, and user-data directory are writable.
- Start the container with the intended sandbox configuration and an init process for Chrome’s child processes.
- Capture a test page in the target container and inspect the logs if Chrome fails before connecting. A change that fixes one class of error may expose a separate runtime issue.
Or skip the browser setup
If maintaining Chrome inside Docker is not the right fit, ScreenshotNeo is a website screenshot API and MCP server for developers. Send one GET request with a URL to receive a PNG, JPEG, WebP, or PDF. For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the API options. Cookie banners are accepted and removed before capture, along with supported consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Troubleshooting quick reference
| Error or behavior | Likely cause | Fix to try |
|---|---|---|
| Missing shared library; Chrome exits before connecting | Unresolved system dependency | Run ldd inside the image, then install the matching distro packages |
Could not find expected browser locally |
Browser download skipped or cache differs between build and runtime | Confirm installation scripts ran; align cache paths or configure a system browser executable |
Executable ENOENT |
Configured browser path does not exist in the container | Check the in-container path and Puppeteer configuration |
No usable sandbox! |
Sandbox cannot operate under current runtime settings | Use the documented sandboxed container setup and required capability where practical |
| Crashpad, profile, or cache startup error | Read-only or incorrectly owned runtime directory | Provide writable XDG and user-data paths with suitable ownership |
| Timeouts on Alpine | Potential browser and Alpine version incompatibility | Verify the exact versions and compatibility; do not rely on an old version-specific workaround without testing |
Performance, reliability, and cost considerations
These sources do not establish benchmark or cost differences between custom and official images. Operationally, a custom image requires you to keep package manifests and browser versions aligned; the official Puppeteer image bundles Chrome for Testing and dependencies, but you still need to manage capabilities, process cleanup, writable storage, and image updates. Rebuild and verify after changing the base image, Puppeteer version, browser version, or package repositories. Pinning deliberate versions improves repeatability, while unreviewed floating tags can change the runtime underneath an application.
Frequently Asked Questions
Does installing Puppeteer automatically install Chrome in Docker?
Installing the puppeteer package normally downloads Chrome for Testing, but install scripts may be blocked. puppeteer-core does not download Chrome.
Can I fix every Puppeteer Docker launch error with --no-sandbox?
No. It does not install missing libraries or browsers, fix unwritable profile paths, or resolve version mismatches, and Puppeteer discourages disabling Chrome’s sandbox.
Quick Recap
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.
Recommended Free Tools
