ERR_OSSL_EVP_UNSUPPORTED in Node 17+? Fix It

You upgrade Node from 16 to 18, run npm start, and the build explodes: Error: error:0308010C:digital envelope routines::unsupported. No code changed. The app ran yesterday. Stack Overflow says add a flag, a teammate says downgrade Node, and your CI pipeline sits red while everyone debates. This is the most common Node-upgrade build failure in the ecosystem, and it has a clean explanation.

Node 17 replaced OpenSSL 1.1 with OpenSSL 3. The new version removed legacy algorithms including MD4 — the default hash in older webpack versions. Your build tool asks OpenSSL for MD4, OpenSSL 3 refuses, and Node surfaces the refusal as ERR_OSSL_EVP_UNSUPPORTED. The error looks cryptographic and scary; the reality is a version handshake between two tools.

This guide covers both horizons: the escape hatch that unblocks your team in five minutes, and the permanent upgrade that removes the flag for good. You'll learn exactly which versions are safe, how NODE_OPTIONS carries the flag, and how to pin Node so this never ambushes another upgrade.

Why Node 17+ Removed MD4 Under Your Build

OpenSSL 3 reorganized algorithms into providers: a default set that's always available and a legacy set that's opt-in. MD4 — fast, old, and cryptographically broken — moved to legacy. Webpack 4 and early webpack 5 used MD4 as their default compilation hash because it was the fastest option when those versions shipped. The combination worked until Node 17 swapped the OpenSSL underneath: same webpack, same config, stricter crypto library, instant build failure at the first hash computation.

This is a supply-chain version handshake, not a bug in your code. Your components, routes, and styles are untouched; only the build tool's internal fingerprinting collides with the new policy. Understanding that layering focuses the fix: change the hash algorithm or re-enable the legacy provider — never rewrite application code in response to a build-time crypto error. Check process.versions.openssl to see which library your Node carries before theorizing further.

OpenSSL 3's provider model explains the blast radius precisely. The default provider ships modern algorithms (SHA-2, AES-GCM, xxhash isn't OpenSSL's — webpack computes it in-process, which is exactly why the upgrade path works), while the legacy provider gates MD4, MD2, DES, and Blowfish behind an explicit opt-in. Webpack 4 and early webpack 5 called EVP_md4 through Node's crypto binding at compilation start, so the refusal hit before any asset compiled — total build failure, zero partial output. Confirm the mechanism directly with node -e "require('crypto').createHash('md4')" on the failing runtime: the thrown code names the policy, proving it's availability, not installation. Other tools share the exposure (old gulp, grunt hashing, some test snapshot serializers), so after fixing webpack, grep the tree for createHash('md4') to catch stragglers before they page you separately.

node -p "process.version + ' / OpenSSL ' + process.versions.openssl"
npx webpack --version
node -e "try { require('crypto').createHash('md4') } catch (e) { console.error('md4 blocked:', e.code) }"
grep '"version"' node_modules/react-scripts/package.json 2>/dev/null

The 5-Minute Escape Hatch: --openssl-legacy-provider

When sixty engineers can't merge, unblock first and cure second. Setting NODE_OPTIONS=--openssl-legacy-provider makes Node load OpenSSL's legacy provider at startup, re-enabling MD4 for every child process including webpack, babel, and test runners. Prefix it on the command line for a one-off verification, export it in your shell for a day of work, or commit it to the Dockerfile ENV and CI env block for team-wide relief.

Treat the flag as borrowed time with a written expiry. It re-enables deprecated cryptography process-wide, must be replicated in every environment (miss one and its builds stay red), and teaches the team that flags substitute for upgrades. File the upgrade ticket in the same PR that adds the flag, with the removal of the flag as the acceptance criterion. The hatch is legitimate incident response; leaving it for a year is deferred maintenance with interest.

Rolling the flag out safely across environments takes more care than the command suggests. Set it in Docker via ENV in the build stage (never baked into runtime images if avoidable), in GitHub Actions via the env block of build jobs, in Vercel/Netlify via project environment settings, and locally via .env files sourced by your shell — then verify each with a build log line echoing the flag's presence. Beware flag conflicts: NODE_OPTIONS with multiple entries needs exact quoting, and some platforms truncate long env values silently. Time-box the flag in the same PR that introduces it — a code comment with the upgrade ticket and a calendar reminder for two sprints out. Teams that skip the expiry ceremony keep the flag for a year; teams that file the ticket delete it within the quarter and wonder why they ever debated the upgrade.

NODE_OPTIONS=--openssl-legacy-provider npm run build
NODE_OPTIONS=--openssl-legacy-provider npx webpack --version
printenv NODE_OPTIONS
node -p "process.version" && npx react-scripts --version 2>/dev/null || true

The Real Fix: Upgrade Webpack and react-scripts

Webpack 5.61 changed the default hash from MD4 to xxhash64 — faster and OpenSSL-3-safe. React-scripts 5 bundles a compatible webpack, so Create React App projects fix this by moving from 4 to 5. The upgrade is the only fix that deletes the flag permanently: after upgrading, rebuild with the flag unset to prove independence. If the build passes with env -u NODE_OPTIONS, the legacy provider is history.

Budget for migration friction honestly. React-scripts 5 brings stricter ESLint, Jest 27, and dropped polyfills for process and buffer that some apps implicitly relied on. Run the upgrade on a branch, fix polyfill imports explicitly where needed, and compare bundle sizes before merging. For custom webpack setups, the surgical alternative is hashFunction: 'xxhash64' in output config — one line that keeps your current version while adopting the safe hash.

Create React App migrations deserve their own checklist since react-scripts 4 to 5 bundles several breaking changes. Jest 27 alters snapshot and timer behavior (run jest -u deliberately, reviewing each snapshot diff), ESLint 8 tightens rules that fail previously green code (budget a lint-fix pass), and dropped Node polyfills (buffer, process, stream) break imports that worked by accident — install browserify polyfills explicitly where the bundle needs them. For custom webpack setups that can't upgrade majors, the surgical line is output.hashFunction: 'xxhash64' (plus hashDigestLength tuning if filenames must stay short). Either path ends the same way: a flag-free build proving independence. Record before/after build times and bundle sizes in the upgrade PR; xxhash64 is measurably faster, and those numbers turn the next upgrade from a debate into a scheduled task.

{
  "dependencies": {
    "react-scripts": "^5.0.1"
  },
  "devDependencies": {
    "webpack": "^5.90.0"
  },
  "engines": {
    "node": "^18.20.0"
  }
}

NODE_OPTIONS Done Right: Scope and Pitfalls

NODE_OPTIONS injects flags into every Node process in its environment — builds, servers, CLI tools, and test runners alike. That breadth is why it works so well as an unblock and why it's risky long-term: the legacy provider stays loaded in production servers that never needed MD4, widening the crypto surface for zero benefit. Scope the flag to build environments (Docker build stage, CI jobs, local shells) rather than runtime images wherever your setup allows multi-stage builds.

Watch for flag collisions too. NODE_OPTIONS with multiple flags needs exact quoting, and some hosting platforms cap env length or strip unknown options. When builds behave differently between environments, printenv NODE_OPTIONS is the first command — a stale or missing flag explains most phantom differences. Document the flag's location in your runbook next to the Node version so the next upgrade starts from facts, not archaeology.

Multi-stage Dockerfiles scope the flag cleanly. Set NODE_OPTIONS in the builder stage where webpack runs, and omit it from the final runtime stage that only executes already-built assets — production servers then never load the legacy provider for a build-time-only problem. Verify the split by inspecting the final image (docker inspect plus grep on Env) and by probing the running process environment. For local development, scope with direnv (.envrc per project) rather than global shell exports, so the flag doesn't leak into unrelated projects on the same laptop. Document the flag's location, purpose, and removal ticket in the runbook beside the Node version entry — the next upgrade starts from facts instead of archaeology. When builds differ between environments, printenv NODE_OPTIONS stays the first diagnostic; flag drift explains most phantom differences.

printenv NODE_OPTIONS
grep -rn 'NODE_OPTIONS' Dockerfile* .github/workflows/ package.json .env* 2>/dev/null | head -20
NODE_OPTIONS='--openssl-legacy-provider --max-old-space-size=4096' npm run build

Pinning Node: .nvmrc, Engines, and CI Alignment

This error is a version-drift error: one environment moved to Node 17+ while the bundler stayed behind. Pinning Node everywhere converts the next upgrade from an ambush into a scheduled event. Commit a .nvmrc with the exact version, declare engines in package.json so installs warn on mismatch, and use the same major in Dockerfiles, CI matrices, and hosting settings. When the team upgrades, all four move in one PR with the webpack compatibility check attached.

Automate the alignment. Shell hooks running nvm use on directory entry keep laptops honest. CI should read .nvmrc rather than hardcoding a separate version that drifts. For Docker, ARG NODE_VERSION consumed by both build and runtime stages guarantees the image matches development. Mixed majors — 16 here, 18 there — guarantee that one person's green build is another's OpenSSL crash.

Volta and fnm deserve mention as nvm alternatives with different tradeoffs. Volta pins Node per project and auto-switches without shell hooks (fast, but requires team-wide adoption), while fnm offers near-instant switches for developers juggling many repos. Whichever manager you choose, the contract is identical: one exact version committed (.nvmrc, volta config, or .node-version), consumed by CI and Docker from the same source, with engines as the backstop. Automate drift detection: a scheduled CI job that diffs .nvmrc against the Dockerfile FROM tag and the CI matrix, failing when they disagree. Onboard every hire with the install-plus-use sequence as step one, documented next to the repo's Node version badge. Version agreement stops being a recurring incident and becomes a file the team rarely thinks about — which is exactly the point.

node:18.20.4
nvm use && node -v
node -p "process.versions.openssl"
npm ls webpack react-scripts --depth=0

Verifying the Cure: Build Clean Without the Flag

Verification has one acceptance test: a clean build with the flag completely unset. Clear caches first — rm -rf node_modules/.cache dist build — because stale MD4 hashes from previous builds can pass while fresh compilations fail. Run env -u NODE_OPTIONS npm run build in each environment: laptop, CI, Docker build, and preview deploys. Green everywhere means the cure holds; red anywhere names the environment still on the old hash.

Lock the result in. Add a CI job that builds with the flag explicitly unset so nobody re-adds it silently. Record the webpack and Node versions in the deploy log for post-mortem archaeology. And close the loop on the incident ticket with before/after build times — xxhash64 is measurably faster, and that number justifies the next upgrade before it becomes the next incident.

Make flag-free verification permanent, not ceremonial. Add a CI job that unsets NODE_OPTIONS explicitly (env -u) before building, so a re-added flag can't silently pass — the job's name should say flag-free so its purpose survives team turnover. Extend the check to preview deploys and Storybook builds, the environments most often forgotten. Keep a build-matrix row pairing the new Node minor with the current webpack on a schedule (weekly is plenty), catching the next handshake issue while it's still a warning in a green pipeline. Close the incident ticket with the full evidence trail: versions before/after, build times, bundle sizes, and the grep proving zero legacy-provider references remain. Future upgrades then start from a runbook with proof attached, and the team that lived through the 9-hour merge freeze never repeats it.

rm -rf node_modules/.cache dist build
env -u NODE_OPTIONS npm run build
npx webpack --version && node -p "process.versions.openssl"
grep -rn 'openssl-legacy-provider' Dockerfile* .github/ .env* package.json 2>/dev/null || echo 'flag fully removed'