Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fsPromises.open() method

Reference for fsPromises.open() in Node.js: open a file and get a FileHandle, flags and mode, closing with finally or await using, and common error codes.

fsPromises.open(path[, flags[, mode]]) opens a file and returns a promise for a FileHandle. The handle stays open until you close it, so you can make several reads, writes and metadata calls on the same file without reopening it. This is the entry point for anything beyond "read it all" or "write it all": reading a header, patching bytes in the middle, tailing a file, or writing records at known positions.

The second argument is a file system flag such as "r" (the default), "w", "a+" or "wx".

NODE
import { open } from "node:fs/promises";

const handle = await open("data.bin", "r");
try {
  const head = Buffer.alloc(4);
  await handle.read(head, 0, 4, 0);
  console.log(head);
} finally {
  await handle.close();
}

Try it

Node.js Reading a header and patching a byte

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js await using, flags and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
fsPromises.open(path[, flags[, mode]]): Promise<FileHandle>
Name Description
path A string, Buffer or URL.
flags A string flag or a number built from fs.constants.O_*. Default "r".
mode Permissions for a newly created file, as a number or an octal string. Default 0o666, reduced by the umask.

Returns: a promise for a FileHandle.

Errors: ENOENT (missing file or parent), EEXIST (exclusive flag on an existing file), EISDIR (directory opened for writing), EACCES/EPERM, EMFILE (too many open files), and ERR_INVALID_ARG_VALUE for an unknown flag string.

Usage notes

  • Always close. Use try/finally, or await using where available (Node.js 24 supports it). An unclosed handle leaks a descriptor, and when the object is garbage collected Node prints a warning and closes it for you.
  • Open once, use many times. Reopening the same file for every small read is slow. Keep the handle for as long as you need the file.
  • EMFILE appears when a process has too many open files, usually from opening thousands in parallel. Limit concurrency, for example with a small pool of workers.
  • Directories can be opened with "r" on Linux and macOS (useful for sync() on a directory), but you cannot read data from them.
  • Flag choice matters: "w" truncates immediately, "r+" does not create, "a" always writes at the end. See File system flags for the full table.
  • The legacy API is different: fs.open() returns a numeric descriptor, not an object. Do not mix descriptors and handles: closing a handle closes its descriptor.
  • Shortcuts exist for whole files. fsPromises.readFile() and fsPromises.writeFile() open and close the file for you.
  • Streams from a handle: handle.createReadStream() and handle.createWriteStream() close the handle when they finish unless you set autoClose: false.