Node.js ERR_OSSL_EVP_UNSUPPORTED Error: Causes and Solutions

Problem Overview

The ERR_OSSL_EVP_UNSUPPORTED error occurs when attempting to build projects with Node.js version 17.0.1 and above. This error manifests as:

Error: digital envelope routines::unsupported

opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
library: 'digital envelope routines',
reason: 'unsupported',
code: 'ERR_OSSL_EVP_UNSUPPORTED'

This issue affects various JavaScript frameworks including Gatsby, React, Vue.js, and Angular, preventing successful project builds.

Root Cause

Node.js 17.0.1 introduced OpenSSL 3.0, which imposes stricter security standards than previous versions. Some cryptographic algorithms and key sizes that were previously allowed are now restricted by default.

The specific issue stems from Webpack's use of the MD4 hash algorithm, which relies on OpenSSL functionality that's no longer supported in OpenSSL 3.0 without explicit configuration.

OpenSSL 3.0 Changes

OpenSSL 3.0 introduced a provider-based architecture and removed support for certain legacy algorithms by default, prioritizing modern cryptographic standards and security practices.

Recommended Solutions

1. Update Webpack (Optimal Solution)

The most sustainable fix is to update Webpack to a version that includes the proper fix:

• Webpack 4: Upgrade to version 4.47.0 or later
• Webpack 5: Upgrade to version 5.61.0 or later

These versions include a WebAssembly implementation of the MD4 algorithm, eliminating dependency on OpenSSL's native implementation.

TIP

Check your webpack version with npm list webpack or yarn list webpack, then update using npm update webpack or the appropriate package manager command.

2. Use OpenSSL Legacy Provider (Temporary Workaround)

For immediate fixes without updating dependencies, use the --openssl-legacy-provider flag:

Environment Variable Approach

export NODE_OPTIONS=--openssl-legacy-provider

Then run your build command normally.

Package.json Script Modifications

React

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

Vue.js

"scripts": {
  "serve": "NODE_OPTIONS=--openssl-legacy-provider vue-cli-service serve",
  "build": "NODE_OPTIONS=--openssl-legacy-provider vue-cli-service build"
}

Cross-Platform (using cross-env)

"scripts": {
  "build": "cross-env NODE_OPTIONS='--openssl-legacy-provider' vue-cli-service build"
}

Windows Users

On Windows, the syntax differs slightly. Use this format instead:

"scripts": {
  "start": "set NODE_OPTIONS=--openssl-legacy-provider && react-scripts start"
}

3. Node Version Management (Alternative Approach)

If temporary workarounds aren't suitable, consider using a Node version manager to switch between versions:

# Using nvm (Node Version Manager)
nvm install 16
nvm use 16

# For Windows users with nvm-windows
nvm install 16.13.0
nvm use 16.13.0

Downgrading Considerations

While downgrading to Node.js 16 provides immediate relief, this approach delays addressing the underlying compatibility issue and may expose you to security vulnerabilities addressed in newer Node.js versions.

Framework-Specific Instructions

Gatsby

Update your build script in package.json:

"scripts": {
  "build": "NODE_OPTIONS=--openssl-legacy-provider gatsby build"
}

Angular

Modify your Angular scripts:

"scripts": {
  "start": "NODE_OPTIONS=--openssl-legacy-provider ng serve",
  "build": "NODE_OPTIONS=--openssl-legacy-provider ng build"
}

Long-Term Recommendation

While the OpenSSL legacy provider workaround resolves immediate build issues, the optimal long-term solution is to:

1. Update Webpack to a compatible version (4.47.0+ or 5.61.0+)
2. Keep Node.js updated to benefit from security patches and performance improvements
3. Monitor framework-specific updates that address OpenSSL 3.0 compatibility

Version Compatibility

Most modern frameworks have released updates that properly handle OpenSSL 3.0 compatibility. Check your framework's documentation for specific guidance.

Conclusion

The ERR_OSSL_EVP_UNSUPPORTED error results from OpenSSL 3.0's stricter security standards in Node.js 17+. While temporary workarounds exist using the legacy OpenSSL provider, the recommended solution is updating Webpack to a compatible version that implements MD4 hashing without relying on deprecated OpenSSL functionality.

By addressing this issue proactively, you ensure both project stability and maintain security best practices across your development environment.