Puppeteer Version Mismatch: Why Your Cache Isn't Working
When deploying a Laravel application that relies on spatie/browsershot to capture screenshots, encountering the "Could not find Chrome" error is a common frustration. The stack trace clearly indicates that Puppeteer cannot locate the executable binary for version 119.0.6045.105. However, inspecting your cache directory might reveal something confusing: a folder named linux-115.0.5790.170 exists within /home/sail/.cache/puppeteer/chrome.
This discrepancy between the error message and the existing files is not a bug; it is a strict versioning constraint enforced by Puppeteer. The core issue lies in the fact that Puppeteer does not treat its cache as a generic repository where any Chrome binary will do. It expects the exact executable path specified in its internal metadata to match the actual file on disk. If your application is requesting Chrome 119 but your cache only contains Chrome 115, Puppeteer refuses to launch the browser to prevent runtime incompatibilities, even though a browser binary technically exists in the folder.
To resolve this, you must ensure that the specific version requested by the code matches the version installed in the cache. The most straightforward approach is to reinstall the browser binaries for the correct version. Since you are running this within a Laravel Sail environment (indicated by the /home/sail path), you should execute the installation command directly in the project's root directory where your node_modules reside.
Run the following command to install the specific Chrome version required by the latest Puppeteer:
npm install puppeteer
npx puppeteer browsers install chrome
If you are using a specific Puppeteer version that pins a different Chrome release, ensure that the --version flag matches your needs. However, modern versions of Puppeteer typically auto-resolve to the latest stable channel. If you are on an older version of the package and need to stick with Chrome 115, you must explicitly install that version:
npx puppeteer browsers install chrome --version 115.0.5790.170
Once the correct binary is downloaded and cached in /home/sail/.cache/puppeteer, the spatie/browsershot package will be able to locate it, and the screenshot action should execute successfully.
Configuring Custom Paths
If you cannot modify the cache or need to point Puppeteer to a system-installed Chrome instance instead of the bundled one, you must configure the executable path explicitly. This is often necessary in production environments where bundling heavy binaries into Docker images is undesirable.
You can pass a custom executablePath option when launching the browser. For instance, if Chrome is installed globally via your package manager at /usr/bin/google-chrome, you can modify your Browsershot configuration like this:
use Spatie\Browsershot\Browsershot;
$screenshot = Browsershot::image('https://example.com')
->screenshot()
->save(__DIR__ . '/screenshots/example.png');
Note that spatie/browsershot wraps the underlying Puppeteer logic. While it supports passing options, you often need to ensure the environment variable PUPPETEER_EXECUTABLE_PATH is set or use the specific API method available in your version to override the default launcher behavior. In many cases, simply ensuring the cache contains the correct version is cleaner than managing external paths.
Headless Mode and Sandbox Flags
The error log shows arguments like --no-sandbox being passed. This is standard for containerized environments where Docker security contexts restrict Chrome from accessing host filesystems. While this flag bypasses security checks, it does not fix version mismatches. Relying on sandbox bypasses without fixing the underlying version conflict will only delay the inevitable crash when Puppeteer attempts to validate the browser's capabilities against the requested API.
Summary of Steps
- Verify the mismatch: Check
ls /home/sail/.cache/puppeteer/chrometo confirm the folder name matches the error message. - Reinstall the correct version: Use
npx puppeteer browsers install chrometo fetch the latest or specific version matching your Puppeteer installation. - Clear stale cache (Optional): If you are unsure of which version is cached, deleting the contents of
/home/sail/.cache/puppeteerand reinstalling ensures a clean state, though this adds download time.
By aligning the installed Chrome binary version with the one Puppeteer expects, you eliminate the ProcessFailedException and restore screenshot functionality to your Laravel app.
