Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Node.js fs/promises: Read, Write, Watch, and Atomic File Operations

writeFile truncates before writing, so a crash leaves half a file. The atomic pattern is temp file, fsync, rename; readFile loads everything, so large files need streams.

~4 min readNode.js
#Node.js#fs#Filesystem#Async
3D illustration of file folder slabs with read and write arrows, a temporary swap tile and a watch eye

Quick Summary

node:fs/promises is the promise-based API over the same libuv file operations as node:fs: each call runs off the main thread and resolves when libuv reports completion. It is the default choice for application code, with node:fs sync calls reserved for startup, CLI scripts, and tests where blocking is acceptable.

Two behaviours are worth knowing before using it. writeFile is not atomic: a crash mid-write leaves a truncated file, and a concurrent reader can see a half-written one. And readFile loads the whole file into memory, so a 2 GB log file is an out-of-memory error, not a slow call.

Atomic replacement is a pattern, not a function: write a temporary file in the same directory, fsync it, rename it over the target. Rename within one filesystem is atomic on POSIX; anything across filesystems fails with EXDEV.

Basic Syntax and Core Signatures

js
import { readFile, writeFile, appendFile, copyFile, rename, rm, mkdir, rmdir, readdir, stat, lstat, open, cp, watch, access, constants, } from 'node:fs/promises'; import { join } from 'node:path'; // Read const text = await readFile('config.json', 'utf8'); const buf = await readFile('image.png'); // Buffer const { size, mtime, mode } = await stat('config.json'); const entries = await readdir('.', { withFileTypes: true }); const all = await readdir('.', { recursive: true, withFileTypes: true }); // Node 18.17+ // Write await writeFile('out.json', JSON.stringify(data, null, 2), { mode: 0o600 }); await writeFile('log.txt', 'line\n', { flag: 'a' }); // append await appendFile('log.txt', 'line\n'); // Directories and removal await mkdir('cache/thumbs', { recursive: true }); // idempotent await rm('tmp', { recursive: true, force: true, maxRetries: 3 }); await cp('src', 'dst', { recursive: true, force: true }); // Node 16.7+ // Handle-based work const fh = await open('data.bin', 'r'); try { const { bytesRead, buffer } = await fh.read(Buffer.alloc(1024), 0, 1024, 0); } finally { await fh.close(); } // Watching const ac = new AbortController(); for await (const { eventType, filename } of watch('src', { recursive: true, signal: ac.signal })) { console.log(eventType, filename); }
js
// The atomic replace, in full import { open, rename, rm } from 'node:fs/promises'; import { dirname, join } from 'node:path'; import { randomBytes } from 'node:crypto'; export async function writeFileAtomic(path, data) { const tmp = join(dirname(path), `.${randomBytes(6).toString('hex')}.tmp`); const fh = await open(tmp, 'w'); try { await fh.writeFile(data); await fh.sync(); // durability: survives a power loss } finally { await fh.close(); } try { await rename(tmp, path); // atomic within one filesystem } catch (err) { await rm(tmp, { force: true }); throw err; } }

Key Comparison Table

FunctionAtomicCreates parent dirsLoads whole fileUse for
writeFileNoNo (ENOENT)YesSmall files, config, JSON
appendFileNoNoYesLogs, line protocol
renameYes, same filesystemNoNoAtomic replace, rotation
copyFileNo, target truncated firstNoInternally streamsPlain copy
cpNoNoStreamsRecursive copy
rm -r -f equivalentNoN/ANoCleanup, temp trees
Error codeMeaningUsual fix
ENOENTPath or parent directory missingmkdir(dir, { recursive: true }) first
EACCESPermission deniedFix mode/ownership; check the process user
EISDIRTried to read a directory as a filereaddir instead
ENOTDIRA path component is a fileCheck each segment
ENOSPCDisk fullClean up; writeFile already truncated the target
EMFILEToo many open filesLimit concurrency, close handles
EXDEVRename across filesystemsCopy then delete, or place the temp file beside the target
EBUSYTarget open elsewhere (Windows)Retry with backoff, rm maxRetries

Practical Edge Cases and Deep Dives

1. Why a half-written JSON file breaks a reader

js
await writeFile('state.json', JSON.stringify(bigState)); // process killed here -> state.json is empty or truncated

writeFile opens with O_TRUNC, which empties the file before writing the new bytes. A crash, an ENOSPC, or a concurrent reader between those two moments sees an incomplete file, and JSON.parse throws Unexpected end of JSON input. The temp-file-plus-rename pattern fixes all three: readers either see the old file or the whole new one. fh.sync() before the rename is what makes it survive a power loss — without it the rename can land before the data reaches disk.

2. mkdir first, and the ENOENT that is not a missing file

js
await writeFile('logs/app/2026-11-15.log', line); // ENOENT: no logs/app directory await mkdir('logs/app', { recursive: true }); // creates both levels, no error if present await writeFile('logs/app/2026-11-15.log', line);

recursive: true makes mkdir idempotent and returns the first directory it created (or undefined when everything existed), which is safe to call on every write path. writeFile and appendFile never create directories — a service that writes per-tenant paths fails with ENOENT the first time a new tenant appears, and the error message names the file, not the missing directory, which sends people looking in the wrong place.

3. Reading a directory tree without recursion bugs

js
const files = await readdir('src', { recursive: true, withFileTypes: true }); for (const dirent of files) { if (!dirent.isFile()) continue; const full = join(dirent.parentPath, dirent.name); }

withFileTypes returns Dirent objects, so no stat per entry; recursive: true (Node 18.17+) walks subdirectories and sets parentPath. Without it, a hand-written recursion that follows symlinks can loop forever — Dirent.isSymbolicLink() is the check, and lstat rather than stat is the way to inspect a link without following it. On a large tree, streaming the directory (opendir) uses constant memory where readdir materialises every entry.

4. watch and the platform differences that matter

js
import { watch } from 'node:fs/promises'; for await (const { eventType, filename } of watch('src', { recursive: true })) { if (eventType === 'change' && filename?.endsWith('.ts')) rebuild(filename); }

fs.watch uses inotify on Linux, FSEvents on macOS, and ReadDirectoryChangesW on Windows, so the same code sees different event coalescing: one edit can produce two change events on macOS and none on a network filesystem. recursive works on macOS and Windows everywhere, on Linux from Node 19.1 onwards with inotify watch limits (fs.inotify.max_user_watches) as a practical ceiling. Watchers also miss events during their startup window, so a build watcher should do one full pass at start, then treat events as hints.

5. Concurrency, EMFILE, and the file-handle limit

js
async function mapLimit(items, limit, fn) { const queue = [...items]; const workers = Array.from({ length: limit }, async () => { while (queue.length) await fn(queue.shift()); }); await Promise.all(workers); } await mapLimit(paths, 16, (p) => readFile(p, 'utf8'));

Promise.all(paths.map(readFile)) opens every file at once and dies with EMFILE: too many open files at a few thousand. The limit is per process (ulimit -n), and the fix is a concurrency cap plus closing handles — a FileHandle that is never closed leaks one descriptor until GC, so try/finally around open is not optional. For hot paths, a small descriptor pool or readFile (which closes internally) is simpler than caching handles.

6. Streams, signals, and when not to use readFile

js
import { createReadStream } from 'node:fs'; import { pipeline } from 'node:stream/promises'; import { createGzip } from 'node:zlib'; await pipeline( createReadStream('big.log'), createGzip(), (await import('node:fs')).createWriteStream('big.log.gz'), );

readFile on a file larger than the heap throws ERR_STRING_TOO_LONG or runs out of memory, and even a 200 MB read costs a full allocation and a GC pause. Anything user-sized goes through streams. Both APIs accept an AbortSignal (readFile(p, { signal })), which is how a request handler cancels a file read when the client disconnects; without it the read finishes into a response nobody will receive.

Common Node.js Runtime Mistakes

SymptomCauseFix
ENOENT on write to a nested pathParent directory missingmkdir(dir, { recursive: true })
Unexpected end of JSON input after a crashwriteFile truncates before writingTemp file + rename (+ sync)
EMFILE under loadUnbounded concurrent opensCap concurrency, close handles
ERR_FS_FILE_TOO_LARGE or OOMreadFile on a huge fileStream it
Watcher misses editsPlatform coalescing, startup window, watch limitsFull pass at start, raise inotify limits
EACCES on a file the user can readDifferent user in the containerMatch UID, or fix ownership
EXDEV on renameTemp file on another filesystemCreate the temp beside the target
Setuid bits lost on copycopyFile copies mode, not ownershipchmod/chown explicitly
Directory read returns EISDIRreadFile on a directoryreaddir
Aborted request still reads the fileNo signal passedPass req.signal into the fs call

Try matching browser tools

All tools

Small utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Node.js guides

More in Node.js

All Node.js guides

The guides filed next to this one in Node.js, in library order.