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
NODE_OPTIONS
environment variable
Set the 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:
- Set the
NODE_OPTIONS
environment variable to--openssl-legacy-provider
. - Use the
--openssl-legacy-provider
flag in yourpackage.json
scripts. - Set the
NODE_OPTIONS
environment variable right before issuing the command. - 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.