ERR_OSSL_EVP_UNSUPPORTED Error in Node.js

Problem Statement

The ERR_OSSL_EVP_UNSUPPORTED error occurs when using Node.js version 17+ with certain development tools like Next.js, React, or webpack-based projects. This error manifests as:

Error: error:0308010C:digital envelope routines::unsupported

The issue stems from changes in OpenSSL 3.0, which was introduced in Node.js 17. The new OpenSSL version removed support for older hash algorithms that some build tools still rely on.

Root Cause

Node.js 17+ includes OpenSSL 3.0, which deprecated certain legacy cryptographic algorithms that were previously available. Build tools like webpack (used by Next.js, Create React App, and similar frameworks) may still attempt to use these deprecated algorithms for hash generation during the build process, causing the runtime error.

This issue typically affects:

• Next.js projects
• React applications
• Webpack-based builds
• Docker containers using Node.js 17+
• Development servers

Solutions

1. Downgrade Node.js Version (Recommended)

The most straightforward solution is to downgrade to Node.js 16 LTS (Long Term Support), which uses OpenSSL 1.1.1 and doesn't have this compatibility issue.

Using nvm (Node Version Manager)

# Install Node.js 16
nvm install 16

# Set as default version
nvm alias default 16

# Use in current shell
nvm use 16

Manual Installation

Download and install Node.js 16 LTS from the official Node.js website.

2. Environment Variable Workaround

If you need to use Node.js 17+, you can set an environment variable to enable legacy OpenSSL provider support:

Unix/Linux/macOS (including Git Bash on Windows)

export NODE_OPTIONS=--openssl-legacy-provider

Windows Command Prompt

set NODE_OPTIONS=--openssl-legacy-provider

Windows PowerShell

$env:NODE_OPTIONS="--openssl-legacy-provider"

Package.json Script Modification

You can also add the environment variable directly to your npm scripts:

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

WARNING

For Windows users, the syntax differs in Command Prompt:

{
  "scripts": {
    "dev": "SET NODE_OPTIONS=--openssl-legacy-provider && next dev",
    "build": "SET NODE_OPTIONS=--openssl-legacy-provider && next build"
  }
}

3. Docker Configuration

If using Docker, ensure your Dockerfile specifies Node.js 16:

FROM node:16-alpine

# Rest of your Dockerfile configuration

Recommendations

Best Practice

We recommend using Node.js 16 LTS for development and production environments until your build tools fully support OpenSSL 3.0. The LTS version provides better stability and long-term support.

Version Compatibility

Check your framework's documentation for Node.js version compatibility:

• Next.js: Compatible with Node.js 12.22.0 or later
• React: Generally compatible with Node.js 14 or later
• Check your specific package dependencies for any version constraints

Verification

After applying any solution, verify your Node.js version:

node --version

You should see version 16.x.x if you downgraded, or version 17.x.x with the environment variable workaround.

Long-term Outlook

This issue is expected to be resolved as build tools and frameworks update their cryptographic dependencies to be compatible with OpenSSL 3.0. Keep your development tools updated to avoid similar compatibility issues in the future.

Security Note

While the legacy provider workaround resolves the immediate issue, be aware that it uses older cryptographic algorithms that may have security implications. Use this only as a temporary solution until proper updates are available.