Error: ENOENT: no such file or directory

What is ENOENT?

ENOENT stands for Error NO ENTry — a POSIX system error code meaning the named file or directory does not exist at the specified path. Node.js surfaces it whenever a file system operation — readFile, writeFile, stat, unlink, readdir, rename, lstat, scandir, open, and others — cannot find the path you provided.

The error is thrown by the operating system's kernel and passed up through Node.js's libuv layer. The integer value is errno: -2 on Linux/macOS and errno: -4058 on Windows. Both map to the same code: 'ENOENT' string.

Full Error Example

Error: ENOENT: no such file or directory, open '/project/config.json'
    at Object.openSync (node:fs:596:3)
    at Object.readFileSync (node:fs:464:35)
    at Object.<anonymous> (/project/app.js:3:19) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/project/config.json'
}

The error object includes four diagnostic fields:

All Causes at a Glance

Cause 1 – Typo in the path

A single wrong character, missing extension, or incorrect directory name produces ENOENT. Always print the resolved path before assuming the file should exist.

const path = require('path');
const fs = require('fs');

const filePath = path.resolve('./conifg.json'); // typo: conifg
console.log('Looking for:', filePath);           // always print to verify
const data = fs.readFileSync(filePath, 'utf8'); // ENOENT if path is wrong

Cause 2 – Wrong working directory

Relative paths are resolved against process.cwd() — the directory Node.js was launched from, not the location of the source file. Running node scripts/build.js from the project root resolves './config.json' to /project/config.json. Running the same script from inside scripts/ resolves it to /project/scripts/config.json — a different path.

// Diagnose — always print both before hitting the error
console.log('cwd:', process.cwd());
console.log('resolved:', path.resolve('./config.json'));

// Fix: anchor to the source file's location with __dirname
const filePath = path.join(__dirname, 'config.json');
// __dirname is the directory of the current .js file, regardless of cwd

Cause 3 – Intermediate directory doesn't exist

Writing a file to ./output/reports/summary.csv fails with ENOENT if output/ or output/reports/ do not exist yet. The open syscall requires all parent directories to already exist. Create the full directory tree before writing.

const fs = require('fs');
const path = require('path');

const outputDir = path.join(__dirname, 'output', 'reports');

// Creates all missing directories; safe to call even if they already exist
fs.mkdirSync(outputDir, { recursive: true });

fs.writeFileSync(path.join(outputDir, 'summary.csv'), data);

async function writeFileSafe(filePath, content) {
  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
  await fs.promises.writeFile(filePath, content);
}

Cause 4 – Async race condition

Reading a file immediately after triggering an async operation that creates it can fail if the write hasn't finished yet. Always await the write before reading.

// Wrong – read may run before write completes
fs.writeFile('./data.json', content, () => {});
const result = fs.readFileSync('./data.json'); // ENOENT possible

// Correct – await the write first
await fs.promises.writeFile('./data.json', content);
const result = await fs.promises.readFile('./data.json', 'utf8');

Cause 5 – Case sensitivity on Linux

macOS and Windows are case-insensitive by default — Config.json and config.json resolve to the same file. Linux (including most CI/CD and production servers) is case-sensitive. Code that works locally can throw ENOENT in production or CI.

// Wrong on Linux (actual file is config.json)
const data = fs.readFileSync('./Config.json');  // ENOENT on Linux

// Correct – match the filename exactly
const data = fs.readFileSync('./config.json');

If you are unsure of the exact case, list the directory contents with fs.readdirSync(dir) and compare programmatically, or use your terminal to ls the directory and inspect every character.

Cause 6 – Hardcoded absolute paths

Absolute paths like /home/alice/project/data.csv or C:\Users\alice\project\data.csv only work on one specific machine. Use __dirname or environment variables to make paths portable across machines, Docker containers, and CI environments.

// Wrong – breaks on every other machine or in Docker
const data = fs.readFileSync('/home/alice/project/data.csv');

// Correct – relative to the source file
const data = fs.readFileSync(path.join(__dirname, 'data.csv'));

// Also correct – configurable via environment variable
const dataPath = process.env.DATA_PATH || path.join(__dirname, 'data.csv');
const data = fs.readFileSync(dataPath);

Cause 7 – Broken symbolic link

A symbolic link whose target has been moved or deleted causes ENOENT even though lstat can see the link entry itself. The error fires on stat, readFile, or any operation that follows the link.

// Detect a broken symlink
try {
  const realPath = fs.realpathSync(linkPath);
  console.log('Resolved to:', realPath);
} catch (err) {
  if (err.code === 'ENOENT') {
    console.error('Broken symlink at:', linkPath);
    // Option A: remove the broken link
    fs.unlinkSync(linkPath);
    // Option B: recreate it pointing to the correct target
    fs.symlinkSync('/correct/target/path', linkPath);
  }
}

To find all broken symlinks in a project tree, run in your terminal:

# Find broken symlinks (Linux/macOS)
find . -type l ! -exec test -e {} \; -print

Cause 8 – __dirname undefined in ES Modules

When using ES Modules (files with .mjs extension or "type": "module" in package.json), the CommonJS globals __dirname and __filename are not defined. Code that uses them will throw a ReferenceError, and paths built without them often produce ENOENT.

// CommonJS (works in .cjs or without "type": "module")
const path = require('path');
const filePath = path.join(__dirname, 'config.json'); // works

// ES Module fix — reconstruct __dirname from import.meta.url
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import { readFileSync } from 'fs';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const filePath = join(__dirname, 'config.json'); // correct in ESM
const data = readFileSync(filePath, 'utf8');

Cause 9 – File missing from Docker image or CI workspace

Code that reads a configuration file, seed data, or template that exists locally but was never copied into the Docker image — or was gitignored and therefore absent from CI — will throw ENOENT in production or CI even though it works locally.

# Dockerfile — make sure to COPY the required files
FROM node:20-alpine
WORKDIR /app

COPY package*.json ./
RUN npm ci

# If config.json is required at runtime, copy it explicitly
COPY config.json ./
COPY src/ ./src/

CMD ["node", "src/index.js"]

In CI (GitHub Actions, GitLab CI, etc.), check that the file is not in .gitignore and that any required secrets or config files are provided via environment variables or CI secrets rather than committed files.

Cause 10 – npm / node_modules ENOENT

Running npx, npm run, or any script that executes a binary from node_modules/.bin/ when node_modules is missing or partially deleted will throw ENOENT with a path inside node_modules.

# Symptom
npm ERR! code ENOENT
npm ERR! syscall lstat
npm ERR! path /project/node_modules/.bin/webpack

# Fix 1 – install dependencies
npm install

# Fix 2 – full clean reinstall (fixes corrupted node_modules)
rm -rf node_modules package-lock.json
npm install

# Fix 3 – if using a monorepo, run install from the workspace root
cd /project-root && npm install

Cause 11 – Windows path separators

On Windows, paths use backslashes (\) as separators. String-concatenating paths with hardcoded forward slashes or backslashes produces paths that fail on the other OS. Always use path.join() which uses the correct separator for the current platform.

// Wrong – fails on Windows because of forward slashes, or Linux because of backslashes
const filePath = __dirname + '/data/' + filename;
const filePath2 = __dirname + '\\data\\' + filename;

// Correct – path.join() uses the right separator for the current OS
const filePath = path.join(__dirname, 'data', filename);

Safe File Access Patterns

Check before reading (synchronous)

if (fs.existsSync(filePath)) {
  const data = fs.readFileSync(filePath, 'utf8');
} else {
  console.warn('File not found:', filePath);
  // use a default value or throw a user-friendly error
}

Handle the error gracefully with try/catch (recommended)

try {
  const data = await fs.promises.readFile(filePath, 'utf8');
  return data;
} catch (err) {
  if (err.code === 'ENOENT') {
    // File doesn't exist — this is expected in some cases
    console.error('File not found:', err.path);
    return null; // or return a default
  }
  throw err; // re-throw unexpected errors (EACCES, EMFILE, etc.)
}

Async existence check with fs.access (no race condition)

// fs.access checks accessibility without opening the file
// Use F_OK to check existence, R_OK for read permission
try {
  await fs.promises.access(filePath, fs.constants.F_OK);
  const data = await fs.promises.readFile(filePath, 'utf8');
} catch (err) {
  if (err.code === 'ENOENT') {
    console.error('File does not exist:', filePath);
  } else {
    throw err;
  }
}

Ensure directory exists before writing

async function writeFileSafe(filePath, content) {
  // mkdir with recursive:true is a no-op if the directory already exists
  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
  await fs.promises.writeFile(filePath, content, 'utf8');
}

await writeFileSafe(path.join(__dirname, 'output', 'report.json'), JSON.stringify(data));

Reading a file with a fallback default

async function readJsonOrDefault(filePath, defaultValue) {
  try {
    const text = await fs.promises.readFile(filePath, 'utf8');
    return JSON.parse(text);
  } catch (err) {
    if (err.code === 'ENOENT') return defaultValue;
    throw err;
  }
}

const config = await readJsonOrDefault(
  path.join(__dirname, 'config.json'),
  { port: 3000, debug: false }  // fallback if config.json doesn't exist
);

Debugging Checklist

1. Read err.path from the error object — it shows the exact absolute path Node.js tried.
2. Print process.cwd() to confirm the working directory at runtime.
3. Print path.resolve('./your/path') to see the absolute path before using it.
4. Check err.syscall to know which fs operation failed (open, stat, scandir, lstat, etc.).
5. Verify the file exists on disk: ls -la /the/path/from/err.path in your terminal.
6. Check if the case of every directory and filename matches exactly on disk.
7. In Docker/CI, confirm the file is actually copied into the image/workspace and is not gitignored.
8. If using ES Modules, ensure you have reconstructed __dirname from import.meta.url.
9. Check for broken symlinks with find . -type l ! -exec test -e {} \; -print.
10. If the error path is inside node_modules, run npm install or a clean reinstall.

Frequently Asked Questions

import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const filePath = join(__dirname, 'config.json');

try {
  const entries = await fs.promises.readdir(dir);
} catch (err) {
  if (err.code === 'ENOENT') {
    console.warn('Directory does not exist:', dir);
  } else throw err;
}

Related Errors

• EACCES: permission denied — the path exists but the process lacks read/write permission
• EMFILE: too many open files — too many file handles open simultaneously; the file exists but cannot be opened
• MODULE_NOT_FOUND — similar "not found" error from the module loader rather than the fs module; triggered by require() or import
• ERR_PACKAGE_PATH_NOT_EXPORTED — the package exists but the specific subpath is not exported in package.json exports map
• ENOTDIR: not a directory — a path component exists as a file, not a directory
• EEXIST: file already exists — thrown by exclusive create operations when the path already exists