When Browsershot fails on a Laravel Forge server, diagnose the exact stage that failed before changing configuration: Node command discovery, Puppeteer module resolution, Chrome installation or cache discovery, browser launch and Linux libraries, or writing the output file. The SSH shell can work while PHP-FPM or a queue worker fails because it runs as a different user with a different PATH, cache, or permissions.
Start by collecting the complete exception and process context. Then follow the branch matching the error instead of applying a generic set of installation commands or Chromium flags.
Capture the failure in the same context that runs the job
Before changing the server, record enough information to reproduce the failure. A short message such as “PDF generation failed” does not distinguish a missing executable from a browser launch or file-write problem.
- The complete exception, including any nested exception and stack trace.
- The exact command Browsershot attempted to run, if it appears in the exception or application logs.
- The process exit code and the complete standard error output (stderr). Preserve the first error in stderr; later messages may only be consequences.
- The working directory, destination path, and whether the failure occurs in a web request, queue worker, scheduled task, or CLI command.
- The identity of the PHP process: its operating-system user and, where relevant, its environment variables and PATH.
- The installed Browsershot, Node, Puppeteer, and Chrome/Chromium versions, plus the Ubuntu release.
Run version and path checks as the same user and through the same runtime that fails. An SSH session opened as your deploy or root account is not proof that PHP-FPM or a long-running queue worker can see the same Node binary, Puppeteer modules, browser cache, or output directory.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- Upgraded Two Zipper Pockets: Forvencer server books feature two secure zipper pockets for better organization of coins, cash, and receipts, ensuring that everything you collect has a safe and secure place
- Smart Storage & Quick Access: Designed with 8 multi-functional compartments, the right side includes a guest receipt pad, while the left has a money pocket, ticket pocket, and credit card slot. Two small clear pockets store bills, receipts, and other visible items. A stitched pen loop ensures you always have your favorite pen ready
- High-quality & Easy to Clean: Crafted from high-quality PU leather with heavy-duty stitching, this server book is built to last. It resists tears, scratches, and its waterproof surface makes cleaning easy with just a damp cloth or a non-chlorine sanitizer
- Perfect Fit for Your Apron: Measuring 5” x 8”, this compact organizer is slightly smaller than other models, making it ideal for bending or sitting while carrying in your server apron. It holds everything a waitress needs—a place for everything
- What's Included: This server organizer comes with multiple open and zippered pockets to store money, receipts, tips, etc. Clear sleeves are perfect for keeping menus or special lists while serving. Available in a variety of colors, allowing you to express yourself even when in uniform
Check the supported version and operating-system baseline
Spatie’s current Browsershot v4 search-result requirements specify Node.js 22.0 LTS or later and Puppeteer 23.0 or later. Its Forge-specific installation instructions target a Forge-provisioned Ubuntu 24.04 server. Because the opened documentation has also exposed older requirements and commands, do not combine instructions from different major versions: check the live, versioned requirements for the Browsershot release installed in your application before running installation commands.
The Forge recipe’s checks include node -v && npm -v; it also describes installing Puppeteer globally, installing Chrome with npx puppeteer browsers install chrome, and installing Ubuntu system libraries. Those steps are version- and OS-specific, not a universal recipe for every Forge machine. Confirm the applicable instructions and Ubuntu release first. The Browsershot repository describes the package as rendering web pages or HTML into images or PDFs through Puppeteer and headless Chrome. Its older v2 and v1 alternatives are not routine fixes: the repository characterizes v2 as unmaintained and v1 as using abandoned PhantomJS.
Diagnose by the stage and exact error
1. Node or npm is missing, or the version is wrong
If the command fails with a message indicating that Node or npm cannot be found, or the version does not satisfy the installed Browsershot release, check discovery and version alignment before investigating Chrome.
- In the failing runtime context, run
node -vandnpm -v. If the error occurs in a queue job, run the checks from that job’s environment or temporarily log its PATH and process user. - Compare the versions with the requirements for the installed Browsershot major version. Do not infer compatibility from an interactive shell that selects a different Node installation.
- If PHP’s PATH omits the executable, configure Browsershot with
setNodeBinaryand, if required,setNpmBinary. UsesetIncludePathto augment the process PATH when that is the actual mismatch. Use the executable path that exists and is accessible to the PHP process. - After changing environment or worker configuration, restart the relevant PHP-FPM service or queue worker so the process picks up the updated environment.
Spatie documents these path configuration methods in its Browsershot documentation. Set explicit paths based on the server’s actual installation; do not copy a path from another machine or user.
Recommended Free Tools
Rank #2
- Upgraded Magnetic Closure Pocket and Two Zipper Pockets: Unlike other brands, Forvencer server books are designed with two secure zipper pockets and two expandable magnetic pockets. These allow you to easily store and organize a large number of coins, cash, and receipts.
- Smart Storage & Quick Lookup: 10 multi-functional compartments. On the right side has a check pad, and on the other has a Money Pocket, Tickets Pocket and Credit Card Slot. Two small clear pockets can store bills, receipts and other items to be viewed. A stitched pen loop to store your favorite pen.
- Long-Lasting and Easy to Clean: Serving book features high-quality PU leather and heavy-duty stitching. PU is extremely strong with high tensile strength and good resistance to tearing, abrasion and scratching. Waterproof leather makes it simple to wipe down your server book with warm water or non-chlorine sanitizer solution to remove any dirt, soil, grime, or soda residue to keep it clean.
- Fit Perfectly in your Apron: Our 5" x 9" server book is designed to accommodate regular checks and fit easily in your apron pocket.
- What You Get: Forvencer server book in strict quality control, our worry-free 1-Year warranty, and friendly customer service.
2. Node reports “Cannot find module ‘puppeteer’”
This means Node was invoked, but the script could not resolve Puppeteer from the module locations available to that process. It is a different failure from Node not being found and from Chrome not being installed.
- Determine whether Puppeteer was installed in the project or globally, and whether that matches how Browsershot launches its Node script.
- Check the module-resolution context for the PHP runtime user. An npm install performed as root, on a developer workstation, or in a different release directory does not by itself make the package resolvable to the production process.
- If Puppeteer is installed in a non-default location, set Browsershot’s
setNodeModulePathto the directory Node should search. Verify that the runtime user can read it. - Align the Puppeteer version with the installed Browsershot version’s requirements, rather than installing an arbitrary version to silence the error.
Once module resolution succeeds, rerun the job. A subsequent “Could not find Chrome” error means execution has moved to a separate browser-discovery stage.
3. Chrome is missing or Browsershot is looking in the wrong cache
For errors such as “Could not find Chrome (ver. 131.0.6778.204),” first verify that the browser installation actually completed. Then check where Puppeteer expects the browser and which user runs PHP or the queue worker.
- Identify the effective home directory and Puppeteer cache directory for the failing process. A community report shows an expected cache under
/root/.cache/puppeteer; that path is evidence of a possible user/cache mismatch, not a path to adopt universally. - Check whether the Chrome installation was performed under a different account or home directory. A browser installed for root may not be discoverable or usable by the deploy user.
- Verify that the executable exists at the location the runtime expects and that the runtime user can traverse its parent directories and execute it.
- If Chrome is installed elsewhere, configure Browsershot with
setChromePathto the actual browser executable, following the installed version’s documentation.
Historical Forge discussions describe changing browser paths, but their examples may concern older versions and different users. Treat them as illustrations of cache ownership and path mismatches, not as current installation instructions.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
4. Chrome starts unsuccessfully or a shared library is missing
“Failed to launch the browser process” is a broad symptom. Read stderr for the specific cause. If it names a missing shared object such as libatk-1.0.so.0: cannot open shared object file, the Linux dynamic loader cannot find a required library.
- Confirm the server’s Ubuntu release, then identify the package that provides the exact missing library for that release.
- Use the system-library list in the current Browsershot requirements for the matching Ubuntu version. The official Forge instructions described in the v4 baseline target Ubuntu 24.04.
- Do not copy dependency package names from an older Ubuntu 22.04 recipe into Ubuntu 24.04, or the reverse, without checking package availability and the current requirements.
- After installing a missing dependency, retry the same job and inspect any new stderr. Fix the next named failure rather than adding unrelated packages.
One Forge-related report names libatk-1.0.so.0; it is an example of a loader error, not evidence that every failed launch needs that library specifically.
5. Browser launches, but the image or PDF is empty or absent
If the browser appears to run but the output is missing, empty, or accompanied by “For some reason Chrome did not write a file at example.pdf,” inspect output writing separately from browser installation.
- Check that the destination directory exists and that the actual PHP or queue-worker user can write there.
- Check permissions on parent directories as well as the output file. A writable file is not useful if the process cannot traverse its directory path.
- Check the Puppeteer cache and browser executable permissions for the same runtime user; successful installation by another user may leave inaccessible files.
- Verify that the job is writing to the path you expect, particularly when the working directory or deployed release changes between CLI and worker execution.
- Use the complete exception and stderr to distinguish a failed navigation or browser process from a successful render followed by a failed file write.
A community discussion reports resolution after changing Node selection and Puppeteer cache permissions. That individual outcome is a useful diagnostic lead, not proof of a universal cause.
Rank #4
- Sturdy, Useful and Attractive: magnetic closure pocket fits a big amount money. The pocket with a zip will keep your coin safe. Sparkly Material and fashionable design help you stand out from the crowd.
- All in one keep your organized: It has everything you need to hold cash, coins, note pads, pen, credit cards and wine/food menu specials.
- Size: 4.7" X 9" organizer fit for most apron.
- Durable and Stretch: High quality soft PU leather for this premium server book, make it light weight and high end.
- Professional:The seams and stitching are done really well and should last as long as you’re using the book. Smooth, rich black finish, looks extremely professional.
6. Change Chromium flags only to address a diagnosed need
Browsershot supports custom Chromium arguments through addChromiumArguments; its documentation also gives a font-rendering example. A public error report includes --no-sandbox and --disable-setuid-sandbox, but that does not show that either flag is required or safe for every Forge deployment.
First identify the launch error and the server’s security model. Only change sandbox behavior if the evidence points to a sandbox-related launch constraint and you have assessed the security trade-off. Do not add a blanket flag set to mask a missing library, incorrect executable path, or permissions error.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Useful Browsershot path controls
Use the control that corresponds to the mismatch rather than changing several paths at once. Spatie documents the following configuration methods:
| Method or control | Use it when |
|---|---|
setNodeBinary |
The Node executable is installed but not found at the path used by the PHP runtime. |
setNpmBinary |
The npm executable needs an explicit path. |
setIncludePath |
The process needs an additional PATH value for executable discovery. |
setNodeModulePath |
Puppeteer is installed in a module directory that Node does not search by default. |
setChromePath |
Chrome is installed, but Browsershot needs its actual executable location specified. |
addChromiumArguments |
A specific, diagnosed browser-launch or rendering requirement calls for an argument. |
Use the current Browsershot documentation for the exact method signature and invocation supported by your installed version. Keep the change narrow: for example, do not change the Chrome path to solve a missing Puppeteer module.
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 →Best Value
- Magnetic Protection: Enhanced Dual Magnetic Protection - The magnetic closure buckle design effectively prevents items from falling out. The interior features a magnetic high-capacity cash pocket that can hold both cash and receipts simultaneously, while a zippered pocket securely stores coins and bills.
- PU Leather: Crafted from premium PU leather with exquisite workmanship, featuring even stitching and easy cleaning. The thickened design makes the server book thicker and Resistant to deformation, strong and durable.
- Multi-functional Compartments: Accommodates cash, credit cards, receipts, loose change, guest checks, pens, and more to meet all your storage needs.
- Best Size: 8 x 5 x 0.9 inches, It is a moderate size that fits most aprons, perfect for carrying around and will make your service job easier.
- Exquisite Design: Professional layout design alleviates service pressure while maintaining orderly organization, enhancing service efficiency. Even in fast-paced restaurant environments, it preserves a professional image and showcases distinctive charm.
A compact diagnostic sequence
- Reproduce once and preserve the full exception, command, exit code, stderr, working directory, process user, and runtime type.
- Check Node and npm versions and executable discovery inside that runtime.
- Check Puppeteer module resolution for the same Node process and runtime user.
- Check Chrome installation, cache location, executable path, and ownership.
- If launch fails, match the first missing library or launch error to the server’s Ubuntu release and security context.
- If rendering runs but output is absent, check destination path, parent-directory traversal, and cache/output permissions.
- Change one relevant setting, restart long-lived processes where needed, and rerun the same job to see whether the failure stage changes.
Or skip the browser setup
If your requirement is simply to capture a web page as an image or PDF, ScreenshotNeo offers a one-request alternative to maintaining Node, Puppeteer, Chrome, and their server dependencies. It accepts a URL and returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)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 removes supported cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server provides screenshot tools for AI agents, and its free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Learn more at ScreenshotNeo.
Sign up for 1,000 free screenshots a month, with no card required.
Questions developers still ask
Should I downgrade Browsershot to an older major version?
Not as a default response to a deployment error. The repository describes the older v2 release as unmaintained and v1 as relying on abandoned PhantomJS. Identify the failed dependency stage and check the requirements for the version your application actually uses before considering a package change.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Do these errors indicate a Laravel Forge outage?
Not by themselves. The error signatures discussed here point to local runtime dependencies, path discovery, browser startup, or file access. The available examples do not establish a Forge-wide incident or the prevalence of any particular cause.
Why does the error change after I fix one issue?
The browser pipeline has multiple dependent stages. Resolving Node discovery can expose module resolution next; resolving that can expose Chrome discovery or a missing Linux library. Record each new error and diagnose the stage it names rather than reverting a valid earlier fix.
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.
