Start with the versions and the deployed browser binary—not a generic “failed to launch” message. Stable Firefox support starts with Puppeteer v23.0.0, and Puppeteer pairs each release with specific browser versions. On Heroku, a launch failure can also mean Firefox was never installed, its configured path is wrong, required Linux libraries are missing, or the buildpack/install lifecycle did not preserve the browser. Capture browser stderr, verify the deployed package and executable, then fix the failing layer.
1. Capture the real launch error on the deployed dyno
Do not diagnose from the wrapper error alone. Puppeteer’s dumpio launch option forwards browser process output to Node’s standard output and error streams, which can reveal a missing library, permission problem, unsupported option, or early browser exit. Temporarily enable it in the Heroku deployment, reproduce the failure, and retain the surrounding application logs.
const puppeteer = require('puppeteer');
async function main() {
const browser = await puppeteer.launch({
browser: 'firefox',
dumpio: true,
timeout: 30000
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await browser.close();
}
}
main().catch(error => {
console.error('Puppeteer launch or page error:', error);
process.exitCode = 1;
});This is a diagnostic starting point, not a guaranteed Heroku recipe. Keep the exact error text and distinguish failure to start Firefox from a later navigation or page error. Remove verbose output after diagnosis if it is no longer needed.
2. Check the Puppeteer version and its paired Firefox
Find the version installed by the deployed lockfile/install, not just the version shown by your local development environment. Puppeteer v23.0.0 and later supports stable Firefox downloads; earlier supported mappings used Firefox Nightly, and older Puppeteer versions did not support Firefox. Puppeteer’s version mapping is intentional: a random system Firefox or the latest Firefox release is not automatically compatible with an older pinned Puppeteer package. See Puppeteer’s supported browsers table and its Firefox support guidance.
#1 Best Overall
Check the version in the Heroku build output or add a temporary startup log:
console.log('Installed Puppeteer:', require('puppeteer/package.json').version);If the deployed package is older than v23, first decide whether to upgrade Puppeteer and use its supported paired browser, or deliberately maintain an older Firefox arrangement. An upgrade can require code and deployment changes; do not assume that changing only the browser binary fixes a release whose Firefox support differs.
3. Verify that Firefox is selected and the executable exists
Puppeteer’s launch options default to Chrome. Make Firefox selection explicit, then verify the path Puppeteer resolves or the custom path you configured. The options include browser, executablePath, dumpio, and timeout; consult the launch options reference for the exact API supported by your installed release.
const puppeteer = require('puppeteer');
console.log('Firefox path:', puppeteer.executablePath('firefox'));
const browser = await puppeteer.launch({
browser: 'firefox',
dumpio: true
});Run path and file-permission checks in the deployed environment or an equivalent Heroku build/runtime context. A path that exists on a developer machine may not exist in the slug or dyno. If you set executablePath, make sure the target is present, executable, and built for the deployed Linux environment.
Recommended Free Tools
Puppeteer cautions that using an externally supplied executable is not guaranteed to work with Puppeteer. Prefer the browser version paired with the installed Puppeteer release unless you have a specific reason to own the browser binary and have validated the pairing.
4. Confirm that the build actually installs and retains Firefox
A successful local install does not prove the Heroku build downloaded Firefox or included it in the deployed artifact. Inspect the build log for the browser installation step, then check the configured executable path after deployment. If the browser was installed in a cache or another location not retained or accessible at runtime, correct the install/buildpack arrangement rather than changing launch flags blindly.
Puppeteer documents browser download and configuration behavior in its configuration guide. Heroku’s Puppeteer troubleshooting guidance discusses adding a Puppeteer buildpack for dependencies, but its recipe is generic and Chromium-oriented; it is not evidence that the same buildpack or exact flags provide a working Firefox installation. The community buildpack README points Firefox users to a separate Firefox-oriented buildpack. Before adopting it, check the repository’s current maintenance state, supported Heroku stack, installation path, and Firefox instructions.
That README also describes a cache workaround for Puppeteer v19+ in the context of its Chrome buildpack instructions. Do not copy a Chrome cache move into a Firefox app without verifying the Firefox buildpack, the package lifecycle, and the actual cache location. Heroku supports custom buildpacks for binaries and dependencies not present in its base image; see Heroku’s buildpack documentation.
5. Diagnose missing Linux libraries and browser requirements
If Firefox exists but exits immediately, inspect its stderr and linked libraries on the same Heroku stack used by the app. Puppeteer’s troubleshooting guide recommends ldd to identify missing shared libraries. Run it against the deployed Firefox executable, or against the same binary in a build/runtime environment that matches the deployed stack:
ldd /path/to/firefoxLook for unresolved entries such as not found. Install only the libraries the chosen Firefox binary actually requires, using a buildpack or package mechanism appropriate for the app’s stack. Do not copy a Chrome dependency list and assume it applies to Firefox. Check Puppeteer’s system requirements for Firefox platform requirements and Linux archive extraction utilities as well.
6. Review buildpack ownership and order
Identify which buildpack is responsible for each item: Node dependencies, Firefox itself, and system libraries. A buildpack can install a browser without necessarily installing all of its runtime dependencies, and the browser may be installed at a path different from the one Puppeteer expects.
- Read the Heroku build log to confirm each buildpack ran and which one installed the browser.
- Check that buildpack ordering allows the dependency and browser installation steps to see the expected files.
- Confirm the Firefox-specific buildpack’s current compatibility with your Heroku stack and Puppeteer release before relying on it.
- Use the actual executable path and library diagnostics to validate the outcome instead of assuming a buildpack name guarantees compatibility.
The generic Puppeteer Heroku troubleshooting page discusses additional dependencies and documents --no-sandbox for its Heroku deployment guidance. Those are general deployment concerns, not a verified Firefox-specific fix. Apply a sandbox argument only when the error and your runtime requirements justify it; do not add flags mechanically.
7. Choose who manages the Firefox binary
| Approach | What it simplifies | What you must verify |
|---|---|---|
| Use the Firefox download paired with Puppeteer | Keeps the browser version aligned with the installed Puppeteer release, as described by Puppeteer’s browser compatibility mapping. | The download runs during the Heroku build, the binary is retained and accessible at runtime, and its Linux requirements are met. |
| Supply a system or buildpack-provided Firefox | Gives you more control over how the browser binary is installed. | Executable path and permissions, compatibility with Puppeteer, required libraries, buildpack maintenance, and compatibility with the selected Heroku stack. |
Neither approach is universally preferable based on the available documentation. The deciding facts are the deployed Puppeteer/Firefox pairing, binary availability, dependency completeness, and buildpack behavior.
8. Redeploy and verify on the same stack
- Make one targeted change based on the evidence: version pairing, browser selection/path, download lifecycle, buildpack configuration, or a missing library.
- Deploy using the same Heroku stack and buildpack configuration intended for production.
- Check the build log for browser installation and the runtime log for Firefox startup output.
- Run a small page load and close the browser in a
finallyblock so the test does not leave a process running. - Remove temporary diagnostic logging when it is no longer needed, while preserving enough operational logging to identify future launch failures.
Common failure patterns and targeted fixes
- Firefox is not supported by the installed Puppeteer release: compare the deployed package version with Puppeteer’s browser table; upgrade to a compatible release or deliberately manage a compatible browser.
- The process cannot find the executable: confirm Firefox was installed in the Heroku build, inspect the actual deployed path, and correct
browserorexecutablePath. - Firefox starts locally but exits on Heroku: use
dumpioandlddon the deployed binary to identify missing libraries or other runtime requirements. - The build log shows no Firefox installation: review Puppeteer download configuration and buildpack ownership; confirm the binary is retained for runtime.
- A Chrome buildpack workaround has no effect: verify that it applies to the Firefox buildpack and its cache layout before reusing it.
- A generic sandbox flag changes nothing: return to stderr and the exact Firefox launch error; generic Chromium-oriented Heroku advice does not establish a Firefox fix.
Or skip the browser setup
If your goal is to capture a website rather than run Firefox inside your Heroku app, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF; its clean-shot process accepts cookie/consent banners like a visitor and removes supported consent platforms, newsletter popups, and chat widgets before capture. Each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and other MCP clients. See ScreenshotNeo and the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpThe free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does Puppeteer support stable Firefox on Heroku?
Puppeteer v23.0.0 and later supports stable Firefox, but that alone does not establish that a particular Heroku buildpack, stack, and dependency setup will launch it successfully.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Should I add –no-sandbox to fix Firefox?
Not automatically. The generic Heroku advice documents that flag in a Chromium-oriented deployment context; use launch output to determine whether it addresses your Firefox failure.
Is the community Firefox buildpack guaranteed to work with my app?
No. Confirm its current maintenance, stack compatibility, installation path, and instructions against your specific Puppeteer release before adopting it.
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.
