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.

Introduction & Quick Summary
Symptom. After moving a service from Node.js 24 to 26, the deploy fails in one of three unrelated-looking ways:
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
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.
// 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" }
}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 ciCore 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:
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.xThe 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
| Behaviour | Node.js 24 | Node.js 26 | Migration |
|---|---|---|---|
fs.rmdir(p, {recursive:true}) | DEP0147 warning | ERR_INVALID_ARG_VALUE thrown | fs.rm(p, {recursive:true, force:true}) |
--experimental-transform-types | accepted | removed, process exits | --experimental-strip-types or a build step |
NODE_MODULE_VERSION | 137 | 147 | npm rebuild or reinstall |
_stream_* modules | present | removed | node:stream |
http.Server.writeHeader() | deprecated | removed | writeHead() |
module.register() | supported | runtime deprecation | module.registerHooks() |
localStorage on the server | undefined | undefined unless --localstorage-file | pass the flag or guard the access |
Temporal | absent | global | feature-detect before use |
| New in 26 | Present in 24 | Reason to use it now |
|---|---|---|
Temporal global | no | dates without the Date pitfalls |
Uint8Array.fromBase64 / toHex | no | binary conversion without Buffer tricks |
Map.prototype.getOrInsert | no | replaces has-then-set |
Iterator.concat | no | chaining iterators |
Promise.try, RegExp.escape | yes | already 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:
grep -rn "rmdir" --include=*.js node_modules | grep recursive | cut -d/ -f3 | sort -uPatch 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:
grep -rn "experimental-transform-types" \
package.json Dockerfile .github/workflows docker-compose.yml .npmrc 2>/dev/nullIf 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:
FROM node:26.13.0-bookworm-slim AS build
RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
&& npm ciKeep 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:
// 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:
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:
NODE_OPTIONS="--throw-deprecation" npm testKeep 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
engineswithout bumping the image. The Docker tag andenginesmust move together, or CI installs for one ABI and runs on another. - Reading the
rmdirerror as a path bug. The message namespath; the rejected argument is the option. - Using
--no-cachein 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 isMODULE_NOT_FOUNDat require time. - Trusting
Temporalon 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 documentationThe Node.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Node.js guides
All Node.js guidesPrisma P2002: Unique constraint failed
The database rejected a duplicate key. Replace check-then-insert with upsert or catch the code deliberately, and read meta.target for the culprit.
npm ERESOLVE: unable to resolve dependency tree
Since npm 7 a peer conflict is a hard error. How to read the tree dump, and when to upgrade, override, use --legacy-peer-deps, or reach for --force.
SyntaxError: Cannot use import statement outside a module
A .js file is CommonJS unless package.json says module. The three valid configurations, the __dirname cascade, JSON import attributes and the browser version of the same error.
ERR_OSSL_EVP_UNSUPPORTED: digital envelope routines on OpenSSL 3
Node 17+ ships OpenSSL 3, where md4 lives in a legacy provider webpack 4 asks for by default. Upgrade, change hashFunction, or bridge with the legacy provider.
More in Node.js
All Node.js guidesThe guides filed next to this one in Node.js, in library order.