fsyncSync on a handle opened with 'r' throws EPERM on Windows, so a durable write that reopens read-only to flush fails only there
env paths · case
Symptom
Section titled “Symptom”A write-then-flush routine that is correct on Linux and macOS dies on Windows at the flush:
error: EPERM: operation not permitted, fsync at fsyncRegularFile (src/lib/service-secrets.ts:70) at writeTokenBackup (src/lib/service-secrets.ts:81)The file is fully written. Nothing is locked. The same code has run for months on POSIX runners. Every caller of the routine — token backup, replace, restore, and a child process that calls it on startup — fails identically, which reads like a permissions problem on the directory until you look at the flags.
import { closeSync, fsyncSync, openSync, writeFileSync } from "node:fs";writeFileSync("probe", "x");const fd = openSync("probe", "r");fsyncSync(fd); // Linux/macOS: fine. Windows: EPERMcloseSync(fd);PS> node repro.mjsnode:fs:... Error: EPERM: operation not permitted, fsyncOpen with "r+" and the same call succeeds.
fsync on Windows is FlushFileBuffers, and FlushFileBuffers requires a handle with
GENERIC_WRITE access. A handle opened for reading only does not have it, so the kernel
refuses with ERROR_ACCESS_DENIED, which libuv maps to EPERM.
POSIX fsync(2) has no such rule: any descriptor for the file will do, because the flush is
about the file’s dirty pages, not the descriptor’s mode. That asymmetry is why “open read-only,
fsync, close” is a common idiom in code that separates the write from the durability step —
the write helper closes its own descriptor, and a later step reopens the path just to flush.
Workaround
Section titled “Workaround”Open the flush handle with write access:
function fsyncRegularFile(path: string): void { const fd = openSync(path, "r+"); // not "r" try { fsyncSync(fd); } finally { closeSync(fd); }}"r+" fails if the file does not exist, which is the right behaviour for a flush of something
you just wrote. If the file may be read-only on disk, O_RDWR will fail too; in that case
flush through the descriptor the write used before closing it, which is also cheaper.
Pin it with a test that spies on openSync and asserts no "r" reaches the flush path; the
contract is invisible on POSIX otherwise. Directory handles are a separate story — Windows
cannot fsync them at all, and that path should be best-effort.