EACCES means a process tried to access a file or directory in a way its permissions forbid. The right fix depends on the path and operation named in the Node.js error: it may be the screenshot destination, Chrome’s executable, or Puppeteer’s cache or browser profile. Read the reported path and syscall before changing permissions; there is no single safe permission command for every case.
Start with the full error, not the screenshot call
Node.js defines EACCES as “An attempt was made to access a file in a way forbidden by its file access permissions.” The error object may also identify the affected path and syscall; those details help distinguish a failed image write from a browser startup or profile failure. See the Node.js Errors documentation.
As an Amazon Associate I earn from qualifying purchases.
Log the complete error and stack, then note error.code, error.path, and error.syscall when present. A screenshot operation can trigger browser access to a cache or profile at the same time, so do not assume the denied path is the output image.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorstry {
await page.screenshot({ path: outputPath });
} catch (error) {
console.error(error);
console.error({
code: error.code,
path: error.path,
syscall: error.syscall,
});
}Identify which path Puppeteer cannot access
| What the error path points to | What to check | Likely direction |
|---|---|---|
| The requested screenshot file or its parent directory | Resolved destination, directory existence, write access for the Node process, and access through parent directories | Use a writable output directory or grant the runtime user the required narrow access |
| Chrome executable or startup files | Browser installation and the specific executable or startup access named by the error | Address the browser installation or platform-specific permissions; changing the image output folder will not fix it |
| Puppeteer cache or browser profile | Configured cache location, userDataDir, container restrictions, and ownership of mounted directories |
Configure writable cache/profile locations for the user running Chrome |
Fix an EACCES error saving the screenshot
Puppeteer’s Page.screenshot() accepts a path to save an image. A relative path is resolved from the process’s current working directory. If you omit path, Puppeteer returns the image data without saving it to disk. See the ScreenshotOptions interface and the Screenshots guide.
#1 Best Overall
- Resolve the destination. Check the absolute path the process is using. A relative path may resolve differently when the script runs under a service manager, test runner, CI job, or container than it does from your terminal.
- Check the directory and every parent directory. The runtime user must be able to create the file in the destination and traverse its parent directories. If the output file already exists, check whether the process can access it as needed.
- Check the actual runtime identity. In a container or CI job, determine which user runs Node and whether a mounted output volume is writable by that user. A directory writable from your development shell may not be writable in the job.
- Use a known writable location as a diagnostic. Temporarily save to an explicit output or temporary directory that the runtime user can write to. If that succeeds, the original destination or its parent permissions are the issue.
- Grant only the needed access. Adjust ownership or permissions on the intended output directory for the application’s runtime user rather than broadly changing permissions throughout the filesystem.
- Verify in the failing environment. Rerun the job under the same user and container or CI configuration, then confirm the image exists at the expected location and can be read.
To avoid a disk write, consume the image bytes returned by Puppeteer:
const image = await page.screenshot({ type: 'png' });
// Use `image` as a Buffer, or send it to the next step in your application.This is useful when the next step can process or upload the image directly. It does not resolve an EACCES error that actually names Chrome’s cache, profile, or executable.
Rank #2
Fix errors involving Chrome startup, the cache, or the profile
If the reported path is not the screenshot destination, changing the output directory is unlikely to help. Puppeteer’s troubleshooting guidance notes that Chrome writes configuration, cache, and profile files during startup. Restricted or read-only environments need suitable writable locations, and a mounted writable directory should be owned or accessible by the user running Chrome.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →- Cache: Check Puppeteer’s configured browser cache location. The troubleshooting guide documents setting it with
PUPPETEER_CACHE_DIRor Puppeteer configuration. - Profile: If the error names browser user data, check the
userDataDirlaunch option and point it to an appropriate writable location when needed. - Container mounts: Check that the mounted directory is writable by the Chrome runtime user, not merely by the host user or build step.
- Read-only environments: Ensure each required cache and profile path has a writable location; making only the screenshot output directory writable is not enough if Chrome cannot start.
Keep cache and profile diagnosis separate: identify which path the error names before changing configuration. Puppeteer’s troubleshooting page says a cache configuration change may require reinstalling Puppeteer to take effect. Follow its current instructions for the installed version: Puppeteer troubleshooting.
Windows: distinguish Chrome sandbox ACL errors
Puppeteer’s troubleshooting guide covers a specific Windows case where Chrome’s sandbox reports that the browser executable lacks required permissions. For applicable installations, the guide says Puppeteer attempts to configure these permissions during installation starting with v22.14.0 and provides a manual icacls example; higher-security environments may need a narrower SID. Use that guidance only when the error matches the browser-executable sandbox case. It is not a general fix for an image path, Linux permissions, or every EACCES error. Consult the current Windows guidance and your environment’s security requirements before changing ACLs.
Common mistakes that make the problem harder to diagnose
- Changing permissions on the wrong path: Match the path in the error to the output, executable, cache, or profile location first.
- Assuming a relative path is relative to the script file: Puppeteer resolves a relative screenshot path from the current working directory.
- Running the whole application as root: This can hide the actual ownership or access problem and grants broader privileges than the screenshot task needs.
- Applying broad recursive permission changes: Avoid changing unrelated files or directories. Give the runtime user only the access needed at the specific location.
- Fixing the host but not the container: A host directory’s permissions do not establish that the configured container user can write to its mount.
Or skip the browser setup
If you need a screenshot rather than a local Puppeteer browser, ScreenshotNeo is a website screenshot API and MCP server. Make one GET request with the target URL to get an image or PDF:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpSee the ScreenshotNeo API documentation for request options. It accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses report the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents using Claude, Cursor, or another MCP client. The Free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
Frequently Asked Questions
Does EACCES mean Puppeteer cannot write the screenshot file?
Not necessarily. It means an access attempt was forbidden; check the error’s path and syscall to identify the operation.
Best Value
- Used Book in Good Condition
Does omitting the screenshot path save the image somewhere by default?
No. Puppeteer returns the image data instead of saving it to disk when the path is omitted.
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.
