As a Node.js developer who has experienced this issue, I’ve conducted research and found out that a breaking change in Node.js version 17, which defaults to OpenSSL version 3, causes error:0308010C:digital envelope routines::unsupported error.

In this article, I will share my understanding of why this error occurs and various ways to fix it.

The reason behind the error

Tools like Webpack utilize the “MD4 algorithm” for generating file hashes, which helps in tracking changes in JavaScript files. OpenSSL version 3, however, does not enable MD4 algorithm support by default.

As a result, upgrading Node.js to version 17 or later will cause this error when building applications with Webpack

For example, this error may occur when running a React application:

$ npm start
Starting the development server...

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

The error stack can be misleading as it does not directly reference the MD4 algorithm that is not enabled by default in OpenSSL 3. I discovered this through GitHub discussions.

Regardless of the type of application (React, Vue, Angular, etc.), this error will occur due to a failed Webpack build.

1. Resolve the error by upgrading to Webpack 5

Webpack 5.61.0 includes a fix for this error, with the maintainer Sokra adding an MD4 implementation using Web Assembly. If Webpack is explicitly used in your package.json file, you can upgrade to version 5:

npm install webpack@latest

However, if your developer tool (e.g., Create React App and vue-cli) internally uses Webpack, you cannot upgrade the Webpack version in this manner.

You will need to wait for the tool to release a new version that resolves this error or use one of the alternative solutions provided below.

2. Include the –openssl-legacy-provider flag in your build script

You can add the --openssl-legacy-provider flag to the build script specified in package.json as an alternative solution.

The OpenSSL legacy provider encompasses a set of legacy algorithms that are no longer widely used, such as MD2, MD4, MDC2, and others.

You can enable these legacy algorithms by adding the flag. Here are some examples for Create React App and vue-cli apps:

// For React:
{
  "scripts": {
    "start": "react-scripts start --openssl-legacy-provider"
  }
}

// For Vue:
{
  "scripts": {
    "serve": "vue-cli-service serve --openssl-legacy-provider"
  },
}

If you encounter an error stating Error: Unknown argument: openssl-legacy-provider, you can set the NODE_OPTIONS environment variable before executing the build command.

Based on your terminal, execute one of the following commands:

# macOS, Linux and Windows Git Bash
export NODE_OPTIONS=--openssl-legacy-provider

# Windows Command Prompt:
set NODE_OPTIONS=--openssl-legacy-provider

# Windows PowerShell:
$env:NODE_OPTIONS="--openssl-legacy-provider"

Next, run your build command, for instance:

export NODE_OPTIONS=--openssl-legacy-provider
npm start

Upon enabling the legacy provider, the error should be resolved.

3. Upgrade react-scripts to v5 for Create React App

For Create React App users, you can resolve this error by upgrading react-scripts to v5.

Execute one of the following commands:

# For npm:
npm install react-scripts@5

# For Yarn:
yarn add react-scripts@5

The react-scripts package now employs the MD5 algorithm to generate Webpack modules and chunks.

Executing the npm start command should no longer display the error.

4. Downgrade Node to v16

Upgrading to Webpack 5 may be challenging for complex applications. In such cases, you can downgrade your Node.js to version 16 while preparing a migration plan from version 4 to version 5.

To install and use Node v16 with nvm, run the following commands:

nvm install 16
nvm alias default 16
nvm use 16

# Check node version:
node -v

For Volta users, execute the commands below:

volta install node@16

# Check node version:
node -v

Volta automatically sets the default node version to the most recently installed one.

Next, delete the node_modules folder and run npm install to rebuild all package dependencies using Node v16. Some dependencies might cause other errors when built with a different Node version.

While this solution works, remember that you will eventually need to upgrade to Node v18 when Node v16 reaches its end of life in September 2023.

It’s advisable to create a migration plan to upgrade Webpack to version 5 during this time.

If the problem is still not resolved let’s try other possible solutions for the error

Set the NODE_OPTIONS environment variable

Set the NODE_OPTIONS environment variable to --openssl-legacy-provider First, try setting the NODE_OPTIONS environment variable to --openssl-legacy-provider.

Open your terminal and execute the appropriate command for your shell type.

# For macOS, Linux, or Windows Git Bash
export NODE_OPTIONS=--openssl-legacy-provider

# For Windows CMD (Command Prompt)
set NODE_OPTIONS=--openssl-legacy-provider

# For Windows PowerShell
$env:NODE_OPTIONS="--openssl-legacy-provider"

# For Docker (in your Dockerfile)
ENV NODE_OPTIONS="--openssl-legacy-provider"

Ensure you use the command corresponding to your shell type. The --openssl-legacy-provider option is necessary when using Node.js 17 or later since it employs OpenSSL 3.0, which introduced some breaking changes.

If setting the NODE_OPTIONS environment variable resolves the issue, you don’t need to apply any of the subsequent changes.

Attempt using the --openssl-legacy-provider flag If the error continues, try adding the --openssl-legacy-provider flag to the command in your package.json file.

For example, this is how you would do it with Create React App:

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

Simply append --openssl-legacy-provider to the end of your command.

If you encounter an error stating that “node: –openssl-legacy-provider is not allowed in NODE_OPTIONS”, unset the NODE_OPTIONS environment variable and retry the command.

# For macOS, Linux, or Windows Git Bash
unset NODE_OPTIONS

# For Windows CMD (Command Prompt)
set NODE_OPTIONS=

# For Windows PowerShell
[Environment]::SetEnvironmentVariable('NODE_OPTIONS', '', 'User')
[Environment]::SetEnvironmentVariable('NODE_OPTIONS', '', 'Machine')

Try running your script again after removing the environment variable.

If the previous solutions don’t help, attempt setting the NODE_OPTIONS environment variable immediately before issuing the command.

Make sure to adjust the command following the environment variable depending on your specific use case.

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

If you execute the command on Windows, you may see an error – “‘NODE_OPTIONS’ is not recognized as an internal or external command”. To fix this, install the cross-env package.

# With NPM
npm install cross-env

# With YARN
yarn add cross-env

Then, prefix the environment variable and the command with cross-env.

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

For an Angular app, your package.json script should look similar to the following:

{
  "scripts": {
    "start": "cross-env NODE_OPTIONS=--openssl-legacy-provider && ng serve -o",
  }
}

If you use Create React App, update your react-scripts version since the package introduced some fixes regarding its Webpack config in version 5.0.0.

Update your react-scripts version if you use Create React App The error may also arise if your Create React App project uses an outdated react-scripts version.

your terminal and run the following command to update your react-scripts version:

# If you use npm
npm install react-scripts@latest

# If you use yarn
yarn add react-scripts@latest

By updating the react-scripts package, you should be able to address the error related to the Webpack configuration.

In summary, to fix the error related to Node.js and OpenSSL, you can try the following steps:

  1. Set the NODE_OPTIONS environment variable to --openssl-legacy-provider.
  2. Use the --openssl-legacy-provider flag in your package.json scripts.
  3. Set the NODE_OPTIONS environment variable right before issuing the command.
  4. Update your react-scripts version if you’re using Create React App.

By trying these different methods, you should be able to resolve the error and continue with your project.