Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Node.js 26 upgrade: rmdir, native addons and removed flags

Three breaks stop a deploy: rmdir with recursive throws, the transform-types flag is gone, and the module ABI moved to 147.

~5 min readNode.js
#Node.js#Native Addons#Upgrade#Troubleshooting
A node cube with a broken rmdir lever and a mismatched binary socket, headline NODE 26 BREAKS

Introduction & Quick Summary

Symptom. After moving a service from Node.js 24 to 26, the deploy fails in one of three unrelated-looking ways:

code
Error [ERR_INVALID_ARG_VALUE]: The argument 'path' must be a string or Uint8Array without null bytes. Received undefined at Object.rmdir (node:internal/fs/utils:...)
node: bad option: --experimental-transform-types
code
Error: The module '/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 137. This version of Node.js requires NODE_MODULE_VERSION 147.

Cause. Node.js 26 makes three separate breaks. fs.rmdir(path, { recursive: true }) was deprecated for years and now throws instead of warning. The --experimental-transform-types flag was removed, so a package.json script or NODE_OPTIONS value that passes it prevents the process from starting at all. And the native module ABI moved from 137 to 147, so every addon with a compiled .node file needs a rebuild.

Fix. Replace the call, drop the flag, rebuild the addons.

js
// before await fs.rmdir(dir, { recursive: true }); // after: idempotent, ignores a missing path await fs.rm(dir, { recursive: true, force: true });
{ "engines": { "node": ">=26.13.0" }, "scripts": { "start": "node --experimental-strip-types src/server.ts" } }
bash
npm rebuild --foreground-scripts # or delete the tree and reinstall so prebuilt binaries for ABI 147 are downloaded rm -rf node_modules package-lock.json && npm ci

Core Mechanics, Signatures & Reproducible Setup

Two things changed at once: the platform (V8 14.6, Temporal on by default, Undici 8) and the support window (26.13.0 became Active LTS on 2026-10-28, while 24 moved to maintenance). The removals are short but each one stops a deploy, because Node refuses to start rather than degrading.

Reproduce the rmdir change on a container without touching your own machine:

docker run --rm -v "$PWD":/app -w /app node:26.13.0-bookworm-slim \ node -e "require('fs').rmdir('/tmp/missing',{recursive:true},e=>console.log(e&&e.code))"

On Node 24 that prints ENOENT and a DEP0147 warning. On 26 it prints ERR_INVALID_ARG_VALUE before it ever looks at the path, because the recursive option is rejected by the binding.

Preflight a repository before upgrading anything:

bash
npm ls --all --parseable | xargs -I{} sh -c 'test -d {}/node_modules && true' grep -rn "rmdir(.*recursive\|--experimental-transform-types" --include=*.js --include=*.ts \ --include=*.json --include=Dockerfile . | grep -v node_modules node -p "process.versions.modules" # 147 on 26.x, 137 on 24.x

The ABI number is the fastest way to confirm a native-addon failure. Anything compiled for 137 is wrong for 147, and Node-API modules, which include sharp and most modern packages, are unaffected because that interface is stable across versions.

Key Comparison Table

BehaviourNode.js 24Node.js 26Migration
fs.rmdir(p, {recursive:true})DEP0147 warningERR_INVALID_ARG_VALUE thrownfs.rm(p, {recursive:true, force:true})
--experimental-transform-typesacceptedremoved, process exits--experimental-strip-types or a build step
NODE_MODULE_VERSION137147npm rebuild or reinstall
_stream_* modulespresentremovednode:stream
http.Server.writeHeader()deprecatedremovedwriteHead()
module.register()supportedruntime deprecationmodule.registerHooks()
localStorage on the serverundefinedundefined unless --localstorage-filepass the flag or guard the access
Temporalabsentglobalfeature-detect before use
New in 26Present in 24Reason to use it now
Temporal globalnodates without the Date pitfalls
Uint8Array.fromBase64 / toHexnobinary conversion without Buffer tricks
Map.prototype.getOrInsertnoreplaces has-then-set
Iterator.concatnochaining iterators
Promise.try, RegExp.escapeyesalready safe to rely on

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. rmdir is the one that hides

The error message from the removed option names the path, not the option, so it reads like a bad argument in your own code. The cause is a dependency calling fs.rmdir with recursive, which was fine on 22 and 24 and is fatal on 26. Find it in your own tree, then in the dependency that owns it:

bash
grep -rn "rmdir" --include=*.js node_modules | grep recursive | cut -d/ -f3 | sort -u

Patch or upgrade the package. Overriding a single call with a patch-package patch is acceptable for a transitive dependency you cannot move yet; wrapping fs globally is not, because it hides the same call from the next upgrade.

2. The removed TypeScript flag

--experimental-transform-types existed to turn enums and namespaces into JavaScript at load time. 26 keeps --experimental-strip-types, which strips types without transforming them, so enum-heavy code has to be compiled or rewritten. The flag can live in four places, and a failure in any of them looks like a broken image:

bash
grep -rn "experimental-transform-types" \ package.json Dockerfile .github/workflows docker-compose.yml .npmrc 2>/dev/null

If you only need types stripped, --experimental-strip-types is enough. If you need enums, run a real build: tsc, tsdown, or esbuild in the Docker build stage. Do not "fix" this by pinning the runtime back to 24 without a plan, because 24 leaves maintenance in April 2028.

3. Native addons and the ABI gap

sharp, bcrypt, better-sqlite3, canvas, node-sass-era packages and older database drivers ship prebuilt binaries. When a prebuild for ABI 147 is missing, npm silently falls back to compiling from source, which needs Python and a C++ toolchain inside the image. That is the usual reason a slim Docker image builds on a laptop and fails in CI:

dockerfile
FROM node:26.13.0-bookworm-slim AS build RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \ && npm ci

Keep the toolchain in a build stage and copy node_modules into the runtime stage, or pin a package version with a 147 prebuild. npm rebuild alone fixes a stale local tree; it does not help when no source is available.

4. module.register() deprecation and loaders

The module.register() API is runtime-deprecated in favour of the synchronous module.registerHooks(). Loaders that instrument imports at startup now warn, and CI running with --throw-deprecation fails instead:

js
// before import { register } from "node:module"; register("./loader.mjs", import.meta.url); // after import { registerHooks } from "node:module"; registerHooks({ resolve(specifier, context, next) { return next(specifier, context); } });

The two are not drop-in replacements: hooks run synchronously on the main thread, which is why the API changed. A loader that performed async I/O during resolution has to move that work.

5. localStorage on the server is still absent

Server code that touches globalThis.localStorage gets undefined, and a client component rendered on the server copies the same assumption. 26 adds --localstorage-file but does not create a default store:

js
const store = typeof localStorage === "undefined" ? null : localStorage;

Guard the access or pass the flag in the test runner only. This bites projects that share an isomorphic storage wrapper between the browser and the server.

6. Deprecations you should convert now, not later

new Buffer(), url.parse(), util._extend, require("sys") and require("punycode") still work with warnings. Run the suite once with --throw-deprecation to turn every warning into a failure and get the list in one pass:

bash
NODE_OPTIONS="--throw-deprecation" npm test

Keep a JSON snapshot of the deprecation output with the JSON formatter so the next upgrade diff is a comparison rather than a hunt.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Bumping engines without bumping the image. The Docker tag and engines must move together, or CI installs for one ABI and runs on another.
  • Reading the rmdir error as a path bug. The message names path; the rejected argument is the option.
  • Using --no-cache in Docker to fix a native build. It recompiles the same failing source; install the toolchain or pin a prebuilt version.
  • Assuming Lambda or Vercel support 26 on day one. Wait for the provider's runtime rather than shipping a custom binary.
  • Leaving _stream_* requires in an old transitive dependency. They are gone, not deprecated; the error is MODULE_NOT_FOUND at require time.
  • Trusting Temporal on 24. Feature-detect it; the polyfill and the built-in behave the same for the common cases but not for exotic calendars.
  • Upgrading Node and TypeScript in one commit. Split them; the exit-code and flag changes mask each other.

Reference: Node.js 26.0.0 release announcement and the Node.js deprecations list.

Official references

primary documentation

The Node.js documentation that defines the behaviour this guide explains.

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.