EACCES
EACCES stands for Error: Access. It means your application found the file or directory, but doesn't have permission to access it.
Usually happens because:
- ☑ Reading a Protected File
- ☑ Writing to a Protected Directory
- ☑ Creating Folders Without Permission
🔍 Quick Checklist:
What is EACCES?
EACCES stands for Error: Access. It means your application found the file or directory, but doesn't have permission to access it. Unlike ENOENT, where the file doesn't exist, an EACCES error means the file is there—Node.js is simply not allowed to read, write, or execute it. This is one of the most common permission-related errors in Node.js applications, especially on Linux and macOS. Imagine a library. The book you're looking for exists. But it's stored in a locked room. You know where it is, but you don't have the key. That's exactly what EACCES means. Node.js found the resource but wasn't allowed to access it.
Common Causes
- Reading a Protected File: Attempting to open a file that only administrators or the owner can access (e.g., /etc/shadow).
- Writing to a Protected Directory: Writing inside system folders (like /root) that normal users cannot write to.
- Creating Folders Without Permission: Modifying directories (like /var/www) without elevated execution roles.
- Using Port 80 or 443: Binding network servers to restricted ports below 1024 without root privileges.
- Incorrect File Permissions: Accessing files whose configuration flags block access for the active user account.
| Cause | Frequency |
|---|---|
| Reading a Protected File | ⭐⭐⭐⭐⭐ |
| Writing to a Protected Directory | ⭐⭐⭐⭐ |
| Creating Folders Without Permission | ⭐⭐⭐ |
Common Mistakes
- Assuming the File Doesn't Exist: Assuming EACCES indicates a missing file when it is actually an access permission restriction.
- Using sudo as the First Solution: Using elevated rights as a quick fix instead of investigating root directory permissions or user roles.
- Writing Application Data to System Folders: Store logs, uploads, and temporary files inside directories your application owns.
- Ignoring Different Deployment Environments: An application may work on your local machine but fail on a server because the server uses different users and permissions.
How to Fix
Framework-Specific Examples
This example catches permission failures during logs writes and advises target directory changes.
import { writeFile } from "node:fs/promises";
async function saveLog() {
try {
await writeFile("/root/log.txt", "Application started");
console.log("Log saved.");
} catch (error) {
if (error.code === "EACCES") {
console.log("Permission denied. Choose a writable directory.");
return;
}
throw error;
}
}
saveLog();Server Configuration Examples
Forwarding privileged port 80 down to Node running on user port 3000.
server {
listen 80;
location / {
proxy_pass http://127.0.0.1:3000;
}
}Best Practices
- Store application data in writable directories.
- Handle EACCES separately from other filesystem errors.
- Avoid running applications as the root user unless absolutely necessary.
- Use higher ports during development.
- Verify permissions before performing file operations.
- Log the full path when debugging permission issues.
Frequently Asked Questions (FAQ)
Q: Is EACCES the same as ENOENT?
No. ENOENT means the file or directory cannot be found. EACCES means it exists, but you don't have permission to access it.
Q: Can EACCES happen when starting an Express server?
Yes. It's common when trying to listen on restricted ports such as 80 or 443 without sufficient privileges.
Q: Does changing file permissions always fix EACCES?
Not always. The problem could also be caused by directory permissions, file ownership, or the user running the Node.js process.
Q: Can EACCES occur on Windows?
Yes. Although permission systems differ, Windows can also return EACCES when access to a file or folder is denied.