How to Fix Puppeteer Firefox Launch Errors After Apt Installation starts with identifying which Firefox you are actually launching. Puppeteer-managed Firefox and an APT-installed Firefox are separate browser routes, with different version pairing, paths, packaging, and failure modes. Capture the exact error and environment first, then follow the branch for browser discovery, archive extraction, or process startup.
There is no single APT-specific fix that is valid for every Ubuntu or Debian host. The steps below use Puppeteer’s current browser guidance and Mozilla’s Linux packaging notes to isolate the real cause without applying Chrome-only commands to Firefox.
1. Capture the facts that determine the fix
Run these commands from the same user and project that launches Puppeteer. Save both stdout and stderr.
node --version
npm ls puppeteer @puppeteer/browsers --depth=0
cat /etc/os-release
which firefox
readlink -f "$(command -v firefox)"
firefox --version
Also record the complete launch code and error, including lines printed by Firefox after the process starts. For Puppeteer’s documented v25.12.0 release, the current system-requirements page lists Node 22.12 or newer. Treat that as documentation for that release, not a timeless requirement for every Puppeteer version.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
- Browser selection: Is the browser downloaded by Puppeteer, or did APT install it separately?
- Version pairing: Which Puppeteer release is installed, and which Firefox release does its supported-browser table specify?
- Executable origin: Does the configured path point to a Puppeteer cache, a DEB executable, a snap launcher, or another wrapper?
- Failure stage: Did installation fail while unpacking an archive, did Puppeteer fail to find a path, or did Firefox start and exit?
- Host details: Which distribution and release, user account, display/headless mode, and container or CI restrictions are involved?
These details prevent a plausible-looking package command from masking the actual fault.
2. Understand the two Firefox installation routes
Puppeteer-managed Firefox
Puppeteer’s browser tooling downloads a browser build into its own cache and pairs browser revisions with each Puppeteer release. The supported-browser guidance says that starting with Puppeteer v23.0.0, Puppeteer downloads and works with the stable Firefox release. The exact pairing remains release-specific, so check the supported-browser list for your installed version rather than copying a version number from another release.
Firefox installed by APT
APT installs or exposes a system browser independently of Puppeteer’s cache. On Ubuntu, /usr/bin/firefox may be a DEB executable, a snap launcher, or another wrapper depending on how Firefox was installed. Mozilla’s current Linux guidance describes DEB and snap routes and warns Ubuntu users who replace the snap with a DEB to pin the Firefox snap in APT before removing it, otherwise the snap can be reinstalled during a later upgrade.
Check the real target instead of trusting the filename:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorscommand -v firefox
readlink -f /usr/bin/firefox
file /usr/bin/firefox
snap list firefox 2>/dev/null || true
dpkg -S /usr/bin/firefox 2>/dev/null || true
A path that resolves to a snap launcher is not equivalent to a native DEB binary. That difference can affect confinement, profile access, environment variables, and how a headless process exits.
3. Verify Puppeteer’s browser and executable configuration
Puppeteer’s configuration API includes browser selection, download settings, and executablePath. Environment overrides can silently change the result. Inspect project files, shell profiles, CI variables, and service definitions for:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
executablePathinpuppeteer.launch()or shared launch options.PUPPETEER_EXECUTABLE_PATHand other Puppeteer configuration environment variables.- The selected browser (Chrome, Chromium, or Firefox) and any Firefox download or cache settings.
- Different configuration files used by local development and CI.
For a diagnostic run, print the path you intend to use and launch it explicitly:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
browser: 'firefox',
headless: true,
executablePath: process.env.FIREFOX_BIN || undefined,
dumpio: true
});
console.log('launched');
await browser.close();
})();
Do not assume that setting executablePath: '/usr/bin/firefox' makes every Puppeteer release support that system browser. The @puppeteer/browsers documentation limits its system-browser launching API to Chrome and Chromium. Firefox discovery through that API is not established; use the supported Puppeteer-managed flow, or an explicitly configured Firefox path only when your installed Puppeteer version documents that use.
4. Repair a Puppeteer-managed Firefox installation
Use the browser paired with your Puppeteer release
First compare your installed Puppeteer version with its supported Firefox entry. If the cache is incomplete or corrupted, repair it with the browser tooling used by that release rather than downloading an arbitrary Firefox build. A typical project-level sequence is:
- Remove or relocate only the broken Puppeteer browser cache, preserving any cache needed by other projects.
- Run the browser installation command documented for your installed Puppeteer release.
- Run the same launch script with
dumpio: trueand capture stderr. - Keep
executablePathunset when you want Puppeteer to select its managed browser.
Do not copy a command intended for a different major Puppeteer version. Browser revision names and command options change with releases.
Install archive utilities on Linux
Puppeteer lists xz and bzip2 as required on Linux to unpack Firefox archives. If installation fails before a browser executable exists, verify them:
command -v xz
command -v bzip2
xz --version
bzip2 --version
On a Debian-family system, install the utilities through your normal package-management policy, then rerun the Puppeteer browser installation. An archive-extraction error is different from a browser that starts and immediately exits; do not troubleshoot shared libraries until extraction succeeds.
Recommended Free Tools
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
5. Launch an APT-installed Firefox deliberately
If you must use the system browser, make the choice explicit and test the binary outside Puppeteer first:
FIREFOX_BIN="$(readlink -f /usr/bin/firefox)"
"$FIREFOX_BIN" --headless --version
Then pass that path only if your Puppeteer release supports Firefox executable configuration:
const puppeteer = require('puppeteer');
(async () => {
const executablePath = process.env.FIREFOX_BIN || '/usr/bin/firefox';
const browser = await puppeteer.launch({
browser: 'firefox',
executablePath,
headless: true,
dumpio: true,
args: []
});
const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'domcontentloaded'});
console.log(await page.title());
await browser.close();
})();
If the managed-browser launch works but this system-browser launch fails, the difference is the executable or its packaging, not Puppeteer’s Node installation. If both fail, return to the captured stderr and host requirements.
6. Match the symptom to the right branch
| Observed symptom | Likely branch | Next check |
|---|---|---|
| “Could not find browser” or a path error | Discovery or configuration | Print executablePath, environment overrides, selected browser, cache location, and whether the expected file exists and is executable. |
| Download, archive, or extraction failure | Puppeteer installation | Check network access, cache permissions, disk space, and the Linux xz and bzip2 commands. |
| Firefox starts, then exits | Process startup | Read Firefox stderr, verify the resolved binary, profile permissions, headless/display settings, and host libraries. The available Puppeteer Linux dependency list is Chrome-focused, not a validated Firefox list. |
Works with a managed browser but not /usr/bin/firefox |
System packaging or unsupported pairing | Identify DEB versus snap, compare Firefox with Puppeteer’s supported table, and confirm that your release documents system Firefox use. |
| Works locally but fails in CI or a container | Environment difference | Compare Node, user ID, filesystem permissions, cache contents, executable resolution, sandbox policy, and display variables. |
7. Avoid the Chrome-only dependency trap
Puppeteer’s browser-management guide scopes Debian/Ubuntu dependency installation to Chrome. Its installDeps option is documented as Chrome-only on Debian/Ubuntu and requires system privileges. Running a Chrome dependency command is therefore not a Firefox fix and can install packages unrelated to the failure.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Likewise, the official Linux troubleshooting material’s shared-library procedure and package list are written for Chrome. Use them only when you are troubleshooting Chrome. For Firefox, let the actual loader or Firefox stderr identify a missing library, then install the package that provides that library for your distribution. Do not present the Chrome list as a Firefox requirement.
8. Ubuntu snap and DEB checks
When Ubuntu’s Firefox command is a snap launcher, test it under the same account that runs Node. Confinement can affect access to home directories, temporary profiles, certificates, and display sockets. When switching to a DEB installation, follow Mozilla’s current pinning procedure before removing the snap; otherwise APT may install the snap again. After any package change, repeat:
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
readlink -f /usr/bin/firefox
firefox --version
firefox --headless --version
Do not infer that APT caused the launch error merely because Firefox was installed with APT. The package origin is one diagnostic variable among version pairing, path selection, archive integrity, libraries, permissions, and headless environment.
9. Reliability and operational practices
Pin the toolchain
Record the Puppeteer major version, Node version, Firefox origin, and browser path in build logs. Upgrade Puppeteer and its paired browser together, then rerun a minimal launch test before changing application code.
Keep caches deterministic
Use a writable, persistent Puppeteer cache in CI when possible. On ephemeral runners, install the documented browser during the job and fail clearly if the archive cannot be unpacked. Avoid sharing a partially populated cache between users.
Collect actionable logs
Enable dumpio for diagnosis, preserve stderr, and remove it or route it deliberately in production. A complete error is more useful than a generic “launch failed” message, especially when the process exits before a page is created.
Test the smallest case
Reduce the launch to headless mode, one page, and no application plugins. Once that works, add custom arguments, proxies, profiles, extensions, and navigation waits one at a time. This separates browser startup from page-level failures.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
For a server-side website image or PDF, ScreenshotNeo provides a single HTTP request instead of maintaining a local Firefox installation. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with the response identifying the page verdict and billing status in headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
See the complete parameter reference in the ScreenshotNeo documentation. A direct call looks like this:
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent 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}`);
Every plan includes the capture options, including full-page lazy-image loading, CSS-selector elements, device and retina settings, PDF controls, custom CSS and JavaScript, clicks, waits, blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data, and an OpenAPI specification. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
10. A concise recovery checklist
- Save the full error and stderr.
- Record Node, Puppeteer, OS, Firefox version, package origin, and resolved executable path.
- Check the Puppeteer supported-browser table for your exact release.
- Remove unintended
executablePathand environment overrides when testing the managed browser. - For managed Firefox downloads, verify
xzandbzip2. - For APT Firefox, distinguish DEB, snap, and wrapper paths with
readlink,file, and package queries. - Use Chrome-only dependency guidance only for Chrome.
- Investigate libraries, sandboxing, display mode, and permissions only after stderr points to them.
Frequently Asked Questions
Does installing Firefox with APT automatically make Puppeteer use it?
No. Puppeteer may select its managed browser or a configured executable. Inspect browser selection, executablePath, environment overrides, and the resolved file.
Should I downgrade Firefox to match an old Puppeteer release?
Do not choose a version by guesswork. Check the supported-browser mapping for the installed Puppeteer release, then use its documented pairing or upgrade Puppeteer and its browser together.
Free tools Windows power users keep installed
One-click scans. No signup required.
Is Ubuntu’s snap Firefox unsupported by definition?
The package type alone does not prove the cause. Establish the resolved path, confinement, permissions, and actual stderr; a snap launcher and a DEB executable are different environments.
Why can a browser version command succeed while Puppeteer still fails?
A version command proves only that the executable can start for that invocation. Puppeteer may use another path, create a profile in an inaccessible location, require headless settings, or encounter a protocol/version mismatch.
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.
