Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readNode.js
#Node.js#OpenSSL#Webpack#Build
3D illustration of a padlock gate with a legacy key plug floating outside and a cyan replacement key

Introduction & Quick Summary

Symptom. npm run build or npm start fails with Error: error:0308010C:digital envelope routines::unsupported and a stack trace that points at webpack/lib/util/createHash.js or crypto.js, plus ERR_OSSL_EVP_UNSUPPORTED. It appears right after upgrading Node, or on a fresh CI image, while the same commit builds fine on a colleague's machine that still runs Node 16.

Cause. Node 17 and later ship OpenSSL 3, which moved md4 — and several other weak algorithms — into an optional legacy provider that is not loaded by default. Webpack 4 and many older tools use md4 for chunk hashes, so the first hash call fails at the OpenSSL layer rather than in JavaScript.

Fix. Three options, in order of durability: upgrade the tool that requests the weak algorithm (webpack 5 uses xxhash64/sha256), set a supported hashFunction, or — as a temporary bridge — start Node with --openssl-legacy-provider. The last one works everywhere NODE_OPTIONS is respected but keeps a deprecated algorithm in the build.

Core Mechanics, Signatures & Reproducible Setup

OpenSSL 3 organises crypto into providers: default, base, and legacy. md4, md2, des, rc4 and rmd160 live in legacy. A lookup for an unavailable digest fails with EVP_R_UNSUPPORTED_ALGORITHM, surfaced by Node as ERR_OSSL_EVP_UNSUPPORTED.

A three-line reproducer that has nothing to do with webpack:

js
// node md4.js const crypto = require('node:crypto'); console.log(crypto.createHash('md4').update('x').digest('hex')); // Error: error:0308010C:digital envelope routines::unsupported

The version matrix is the whole story:

bash
node -p "process.version + ' ' + process.versions.openssl" # v16.20.2 1.1.1w -> md4 works # v20.18.0 3.0.15 -> md4 throws unless legacy provider is loaded

Enabling the legacy provider for a build, without touching application code:

bash
NODE_OPTIONS=--openssl-legacy-provider npm run build # Windows PowerShell $env:NODE_OPTIONS="--openssl-legacy-provider"; npm run build
js
// Or per-process, before any hashing happens const crypto = require('node:crypto'); // node --openssl-legacy-provider script.js

The modern fix, when the tool supports it: tell webpack which hash to use instead of relying on its default.

js
// webpack.config.js (webpack 5: output.hashFunction defaults to md4 in v5.0-5.53, xxhash64 later) module.exports = { output: { hashFunction: 'sha256', // or 'xxhash64' on webpack >= 5.54 hashDigestLength: 16, }, };

Key Comparison Table

Algorithms and their availability under OpenSSL 3:

AlgorithmDefault providerLegacy provider neededNotes
md4NoYeswebpack 4's default chunk hash
md5YesNoDisabled in FIPS mode
sha1YesNoStill available, no longer for signatures
sha256 / sha512YesNoSafe default
ripemd160 (rmd160)NoYesUsed by some Bitcoin libraries
xxhash64N/A (JS/WebAssembly)Nowebpack's fast non-crypto hash
des-ede3-cbcNoYesLegacy cipher, not a digest

The three fixes compared:

FixEffortStays validRisk
Upgrade webpack 4 → 5HighYesConfig and plugin migration
Set output.hashFunctionLowYes, if the toolchain reads itNone for hashing output
--openssl-legacy-providerLowestNoDeprecated algorithms, breaks on FIPS images

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Create React App and react-scripts 4

react-scripts@4 pins webpack 4, so every Node 17+ machine needs a workaround. The two accepted ones are a NODE_OPTIONS prelude in the script, or moving to react-scripts@5:

json
{ "scripts": { "start": "react-scripts start", "build": "NODE_OPTIONS=--openssl-legacy-provider react-scripts build" } }

Setting it inline in package.json is not portable to Windows shells; use cross-env if the team is mixed, or put it in .env (NODE_OPTIONS=--openssl-legacy-provider) which CRA reads for build-time variables.

2. Webpack 5 that still asks for md4

Webpack 5 changed the default hash function to xxhash64 in 5.54 and used md4 before that, so a project on webpack 5.40 pinned in a lockfile still fails on Node 20. Check the installed version instead of the declared range:

bash
npm ls webpack # webpack@5.41.0 -> md4 default npm i -D webpack@^5.97

3. Application code calling crypto.createHash('md4')

A checksum or cache key computed with md4 fails everywhere OpenSSL 3 runs, and a browser build may fail for a different reason. Replace the algorithm rather than the provider; changing a cache key format once is cheaper than keeping a legacy provider alive:

js
// Before const key = crypto.createHash('md4').update(name).digest('hex'); // After: same length class of digest, available everywhere const key = crypto.createHash('sha256').update(name).digest('hex').slice(0, 32);

If the value must stay byte-identical for existing caches, keep the old algorithm behind a version prefix and migrate lazily.

4. FIPS-mode images where the legacy provider cannot load

Some hardened base images build OpenSSL with fips=yes and no legacy module. --openssl-legacy-provider then fails at startup with legacy provider not available, which is a clearer error but still a failed build:

bash
openssl list -providers # Providers: # default # fips

In that environment the only fix is removing the weak algorithm from the toolchain.

5. Docker and CI images that silently changed

A Floating node:18-alpine tag moved from OpenSSL 3.0 to 3.1 and behaviour did not change, but a node:16 to node:20 bump in a base image does. Pin image digests for build tooling and run the build once in the same image the CI uses:

bash
docker run --rm -v "$PWD":/app -w /app node:20-bookworm-slim \ sh -c "npm ci && npm run build"

6. The error without the usual stack

0308010C also appears from crypto.sign/verify with an unsupported digest name, from tls with legacy ciphers, and from aes-256-cbc-style code that asks for an unavailable cipher. Read the first stack frame rather than assuming webpack — the caller of createHash is usually one frame down:

js
for (const alg of ['md4', 'md5', 'sha1', 'ripemd160']) { try { crypto.createHash(alg); console.log(alg, 'ok'); } catch (e) { console.log(alg, e.code); } }

Common Compilation/Runtime Mistakes & Version Gotchas

  • Exporting NODE_OPTIONS only in the shell. CI runners and npm lifecycle scripts may spawn with a clean environment; put it in the script or in .npmrc's node-options (npm 9+) so it applies to every invocation.
  • Assuming Node 18 is the cause. Node 17 introduced OpenSSL 3 in the default builds; 18, 20, 22 and 24 all behave the same way. The version that "worked" was 16.x.
  • --openssl-legacy-provider inside NODE_OPTIONS for Electron. Electron's runtime uses its own OpenSSL; pass the flag to the packaged binary's args or upgrade the bundler, since the Node option does not reach it.
  • Two lockfiles, one toolchain. yarn.lock resolving webpack 4 while package.json asks for 5 means npm ls and the actual build disagree; the error follows the resolved version.
  • Treating a warning as harmless. OpenSSL 3 prints deprecation warnings for legacy algorithms; teams often silence them and only learn of the break when a security review forbids the provider.
  • Pinning hashFunction: 'md4' "for stability". It reintroduces the original failure on any Node with a strict provider; xxhash64 is faster and available in webpack 5.54+.
  • Forgetting the browser bundle. A Node-only fix passes tests in SSR mode and fails the client build, because the client config has its own output block with its own default hash.
  • NODE_OPTIONS dropped by a wrapper. npm run passes it through, but a runner that re-execs node with a cleaned environment (some nx, turbo and jest setups) loses it; pass the flag to the child explicitly.

Related tools. When two branches disagree about a lockfile or a bundler config, paste them into the text diff tool to find the version bump that introduced the failure, and use the hash generator to compare md4/sha256 outputs while migrating cache keys so nothing silently changes identity.

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.