Free tools Windows power users keep installed
One-click scans. No signup required.
If Puppeteer fails after you installed Firefox with APT, first determine which Firefox it is trying to start. Puppeteer-managed Firefox and an operating-system package are separate installations, with different version pairing, paths and failure modes. Capture the exact error and environment, then follow the branch for browser discovery, archive extraction or process startup instead of applying a generic Chrome dependency command.
What “APT-installed Firefox” changes
Puppeteer can download a browser build into its own cache. Firefox installed by Debian or Ubuntu’s package manager is a different binary, possibly a DEB executable, a snap launcher or another wrapper. The selected executable is controlled by Puppeteer configuration and environment overrides; installing Firefox through APT does not automatically make it the browser Puppeteer should use.
Puppeteer’s browser-management documentation states that system-browser launching in its browser API is supported for Chrome/Chromium. Do not assume that the same discovery mechanism locates system Firefox. Use the Firefox build supported by your Puppeteer release, or an explicitly configured executable path only where that release documents the use.
Collect the facts before changing packages
The title alone does not identify a single root cause. Record these values and the complete stderr output from the failed launch:
#1 Best Overall
- Node: run
node --version. Puppeteer’s current system-requirements page for version 25.12.0 documents Node 22.12 or newer; treat that as documentation for that release, not a timeless requirement for every Puppeteer version. - Puppeteer: run
npm ls puppeteer(ornpm ls puppeteer-coreif that is what your project uses). - Operating system: run
cat /etc/os-releaseand note the distribution and release. - Firefox package and path: run
command -v firefox,readlink -f "$(command -v firefox)", and your distribution’s package query (for example,dpkg -S "$(readlink -f "$(command -v firefox)")"when applicable). - Launch details: save the full Node stack trace and Firefox stderr, including whether the process was never found, failed during extraction, or started and then exited.
Check the Puppeteer–Firefox version pairing
Puppeteer’s supported-browser guidance says that stable Firefox support begins with Puppeteer 23.0.0. Each Puppeteer release is paired with particular browser versions so its protocol implementation remains compatible. The mapping changes between releases, so look up the row for your installed Puppeteer version rather than copying a version from another project.
- Identify the installed Puppeteer version with
npm ls puppeteer. - Open Puppeteer’s current Supported browsers page and FAQ, and find the Firefox version mapped to that release.
- If you want Puppeteer-managed Firefox, use the browser tooling for your installed release to install or repair that matching build. Keep the cache writable by the account running Node.
- If you intend to launch a system Firefox, confirm that your Puppeteer release documents that workflow and set its executable path explicitly. Do not pair an arbitrary old APT Firefox with a new Puppeteer release without checking the support table.
A “could not find browser” message usually means the configured path, cache or selected-browser setting is wrong, not that Firefox needs an unverified list of APT libraries.
Inspect configuration and environment overrides
Puppeteer’s configuration API exposes browser selection, executable paths and Firefox download settings. Check your project configuration and shell environment for values that silently override your code:
Rank #2
executablePathin the launch options or configuration file.PUPPETEER_EXECUTABLE_PATH, which can force a system binary.- The selected browser setting and Firefox download/cache controls.
- Container, service-account or CI environment differences: a path that exists for your login user may not exist for the account running the job.
Log the final path immediately before launch. If you choose the APT binary, verify it is executable by the same user and that its target is the intended DEB or snap installation.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallconst browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
headless: true
});Use an explicit path only after confirming that the installed Puppeteer version supports launching that Firefox build. Otherwise remove the override and let Puppeteer use its supported managed browser.
Repair Puppeteer-managed Firefox downloads
When the error occurs while downloading or unpacking a Firefox archive, check the archive utilities first. Puppeteer lists xz and bzip2 as required on Linux for Firefox archives. Install those utilities through your distribution’s normal package process, then rerun the Puppeteer browser installation or repair command for your release.
Rank #3
This branch is different from a process that starts and exits. If extraction completed and Firefox produced runtime stderr, utility packages are unlikely to be the immediate cause. Also check disk space, cache permissions and interrupted downloads before deleting a cache.
Verify what Ubuntu’s /usr/bin/firefox actually is
Mozilla’s Linux installation guidance describes both snap and DEB routes. On Ubuntu, /usr/bin/firefox may resolve to a package-managed executable or a launcher whose behavior differs from a standalone DEB binary. Check the real target on the host instead of assuming the path identifies the package format.
command -v firefox
readlink -f /usr/bin/firefox
ls -l /usr/bin/firefoxIf replacing Ubuntu’s Firefox snap with a DEB, Mozilla instructs users to pin the Firefox snap in the APT package manager before removing it with sudo snap remove firefox, preventing an unwanted snap upgrade or reinstallation. Follow the current instructions for your Ubuntu release; do not remove packages merely because Puppeteer reported a launch error.
Use the error branch that matches the symptom
“Could not find browser”, “ENOENT” or a path error
- Print the configured
executablePathand test it withtest -x /path/to/firefox. - Check whether a cache download was skipped, failed or belongs to another user.
- Confirm the selected browser and remove stale environment overrides.
- Do not assume system Firefox discovery is available through the Chrome/Chromium system-browser API.
Archive extraction or decompression failure
- Verify
xz --versionandbzip2 --versionas the same user that runs the installer. - Check free disk space and write permission to Puppeteer’s cache.
- Retry the matching browser installation after an interrupted download is removed or repaired.
Firefox starts and immediately exits
Capture Firefox’s own stderr and inspect the host libraries, sandbox policy, display/headless mode and permissions indicated by that message. The reviewed Puppeteer Linux troubleshooting material is primarily Chrome-focused; its Chrome package list is not a validated Firefox dependency list and should not be copied as one.
Snap/DEB behavior differs between machines
Compare readlink -f output, package ownership and the Node user’s environment on each host. A snap launcher, a DEB executable and a wrapper can expose different paths and confinement behavior even when the command is named firefox.
Do not use Chrome’s APT dependency fix for Firefox
Puppeteer’s browser-management guide scopes Debian/Ubuntu dependency installation and the installDeps option to Chrome. That operation requires system privileges and is not a Firefox repair command. Running it may install unrelated packages while leaving a Firefox path, version pairing or snap/DEB issue untouched.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsA repeatable clean-launch procedure
- Save the versions, distribution details, executable resolution and full stderr.
- Decide whether the intended browser is Puppeteer-managed Firefox or an OS-installed binary.
- For managed Firefox, select the release-specific supported build and repair its cache; verify
xzandbzip2if installation fails. - For a system binary, confirm the documented support for your Puppeteer release, resolve the path and set it explicitly.
- Run a minimal headless launch under the same account as production, then add your normal viewport, profile and navigation options one at a time.
- Only after stderr identifies a runtime problem, investigate libraries, sandboxing, display settings or permissions relevant to that host.
Performance, reliability and maintenance considerations
- Managed builds: version pairing is explicit and reproducible, but the cache must be downloaded and writable in every deployment environment.
- OS packages: updates follow the distribution’s packaging channel, so Firefox can move independently of Puppeteer’s tested mapping. Pinning and package policy must be managed carefully on Ubuntu.
- CI and containers: install browser utilities and the selected browser during image creation, run as the eventual application user, and record the resolved path in build logs.
- Diagnosis: preserve the first concrete error. Replacing packages before identifying whether the failure is discovery, extraction or startup often obscures the original cause.
Or skip the browser setup
If your goal is a reliable website image rather than controlling Firefox locally, ScreenshotNeo provides a website screenshot API and MCP server. A single request returns PNG, JPEG, WebP or PDF; its capture flow accepts cookie banners and removes more than 60 known consent platforms, newsletter popups and chat widgets before the shot. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status.
See the complete parameter reference in the ScreenshotNeo documentation. Basic cURL usage:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in 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)And 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 also offers an MCP server for Claude, Cursor and other MCP clients, so an AI agent can call take_screenshot, get_page_info or capture_pdf. Every plan includes the features; 1,000 screenshots per month are free without a card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
Frequently Asked Questions
Does installing Firefox with APT automatically configure Puppeteer to use it?
No. Puppeteer’s browser selection and executable path are controlled by its configuration and environment. Verify the actual path and whether your release supports that system-browser workflow.
Is there one Ubuntu package list that fixes every Firefox launch failure?
No. The correct action depends on whether the failure is browser discovery, archive extraction or process startup. Use the Firefox stderr and host details before changing libraries.
Why can two machines resolve firefox differently?
Ubuntu installations can use snap, DEB or wrapper paths. Resolve the command with readlink -f and inspect package ownership on each host.
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.
