Analysis and Solutions for ERR_OSSL_EVP_UNSUPPORTED Error in Node.js 17

Problem Background and Error Analysis

With the release of Node.js 17, many developers encountered the ERR_OSSL_EVP_UNSUPPORTED error after upgrading. This error typically manifests as: Error: digital envelope routines::unsupported, accompanied by detailed OpenSSL error stack information. This phenomenon is particularly common in projects built with webpack, such as Gatsby, React, and Vue.js.

Root Cause Investigation

The fundamental cause of this error lies in the enhanced restrictions on cryptographic algorithms in OpenSSL 3.0. Node.js 17 uses OpenSSL 3.0 by default, which removes default support for some legacy cryptographic algorithms and key sizes. Specifically:

When applications or dependent modules attempt to use algorithms that are no longer permitted by default, OpenSSL 3.0 throws the ERR_OSSL_EVP_UNSUPPORTED error. This is particularly evident in webpack build processes, as webpack in certain versions uses the md4 hash algorithm, which is restricted in OpenSSL 3.0.

Detailed Solutions

Method 1: Using the openssl-legacy-provider Option

Node.js 17 introduced the --openssl-legacy-provider command-line option, allowing temporary reversion to the legacy cryptographic provider. This can be implemented in several ways:

Direct Command Line Execution:

node --openssl-legacy-provider ./node_modules/.bin/gatsby build

Environment Variable Configuration:

export NODE_OPTIONS=--openssl-legacy-provider

Package.json Script Configuration:

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

Method 2: Upgrading Webpack Version

For webpack-related build errors, upgrading to fixed versions is the most fundamental solution:

• Webpack 4 users should upgrade to version 4.47.0 or higher
• Webpack 5 users should upgrade to version 5.61.0 or higher

These versions include custom implementations of the md4 algorithm, no longer relying on Node.js's built-in crypto module, thus avoiding OpenSSL 3.0 restrictions.

Method 3: OS-Specific Script Configuration

Script configurations in package.json need to be adjusted according to different operating systems:

Unix/Linux/macOS Systems:

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

Windows Systems:

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

Technical Principle Deep Dive

OpenSSL 3.0 Security Enhancements

OpenSSL 3.0 introduced stricter security policies, disabling some legacy algorithms considered insufficiently secure by default. This change reflects the evolution of modern cryptographic standards, aiming to enhance overall application security.

Webpack Hash Algorithm Evolution

Webpack uses hash algorithms to generate file fingerprints during the build process. Early versions relied on Node.js's crypto module, while newer versions adopted WebAssembly-implemented md4 algorithms. This architectural change makes webpack no longer constrained by specific OpenSSL version algorithm support.

Best Practice Recommendations

Short-term Solution: For production environments requiring urgent fixes, using the --openssl-legacy-provider option is the fastest resolution method.

Long-term Solution: Upgrade relevant dependencies to the latest versions, particularly webpack and related build tools, to ensure compatibility with the latest cryptographic standards.

Security Considerations: While the legacy provider can solve current problems, developers should be aware of potential security risks. It is recommended to gradually migrate to solutions using modern cryptographic algorithms after resolving compatibility issues.

Conclusion

The ERR_OSSL_EVP_UNSUPPORTED error represents a typical compatibility issue in the evolution of the Node.js ecosystem. By understanding OpenSSL 3.0's security policy changes and webpack's architectural improvements, developers can choose the most suitable solution for their projects. Whether using the legacy provider as a temporary measure or upgrading dependencies for long-term compatibility, decisions should be based on specific project requirements and security considerations.