You pull an older JavaScript project from Git, run npm start, and the terminal suddenly throws an error containing ERR_OSSL_EVP_UNSUPPORTED. The application may have worked perfectly the last time you touched it, but now the development server refuses to start.
This is particularly frustrating with older React applications built using Create React App, projects running older versions of Webpack, and codebases that haven't been updated to match newer Node.js releases.
The first thing to understand is that this error doesn't automatically mean your project is broken. It often appears because an older build tool relies on a cryptographic operation that newer Node.js versions no longer allow by default.
You don't necessarily need to rebuild the application or upgrade every dependency. The right fix depends on your Node.js version, the build tools your project uses, and whether you're trying to get an old project running temporarily or maintain it for the long term.
Why the Error Suddenly Appears
The ERR_OSSL_EVP_UNSUPPORTED error became common after Node.js 17 introduced OpenSSL 3.0.
Some older JavaScript build tools, particularly certain versions of Webpack, used hashing algorithms or cryptographic functionality that OpenSSL 3.0 no longer enables by default.
When the build tool attempts to use an unsupported algorithm, Node.js throws an error instead of completing the build.
The terminal output may include lines similar to these:
node:internal/crypto/hash:69
this[kHandle] = new _Hash(algorithm, x, y);
^
Error: error:0308010C:digital envelope routines::unsupported
code: 'ERR_OSSL_EVP_UNSUPPORTED'You might also see the error when running npm start, npm run build, or another script that launches your project's development tools.
If the project started failing after you upgraded Node.js, that's an important clue. The application code may not have changed at all; the incompatibility could be between the new Node.js runtime and an older dependency.
The Quick Fix: Use the Legacy OpenSSL Provider
If you need to get the project running while you investigate a proper upgrade, Node.js provides a compatibility option:
NODE_OPTIONS=--openssl-legacy-provider npm startThis command works in many Unix-like environments, including Linux and macOS. However, if you're using Windows Command Prompt or PowerShell, the syntax is different.
Windows Command Prompt:
set NODE_OPTIONS=--openssl-legacy-provider
npm startWindows PowerShell:
$env:NODE_OPTIONS="--openssl-legacy-provider"
npm startRun the commands in the terminal you normally use for the project. If the development server starts successfully, you've likely confirmed that the error is related to the OpenSSL compatibility issue.
Keep in mind that this is a workaround, not a permanent solution. The legacy provider enables older cryptographic algorithms that are disabled by default. Use it only when necessary, and avoid treating it as a global setting for every Node.js project.
When you're finished, you can remove the setting from your current PowerShell session with:
Remove-Item Env:NODE_OPTIONSIn Windows Command Prompt, use:
set NODE_OPTIONS=These commands remove the temporary environment setting from the current terminal session.
Make the Fix Work With an npm Script
Typing the workaround every time you start the project gets old quickly. You may want to put it into your package.json scripts, but be careful about the operating system.
For a project where you specifically need this workaround, you could configure a script for Unix-like shells:
{
"scripts": {
"start:legacy": "NODE_OPTIONS=--openssl-legacy-provider npm start"
}
}However, don't add that exact script if it calls itself recursively. If your existing start script launches the development server, a separate script should invoke the underlying tool or the existing command without calling npm start again.
For example, if your original scripts look like this:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build"
}
}You can add a separate Unix-compatible workaround script:
{
"scripts": {
"start": "react-scripts start",
"start:legacy": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start"
}
}This lets you run the normal command when it works and use npm run start:legacy only when necessary.
That syntax is not directly compatible with Windows Command Prompt. If your team uses multiple operating systems, consider using a cross-platform environment-variable tool such as cross-env, or keep the workaround in your terminal instead of embedding it in the project.
If you use cross-env, install it as a development dependency:
npm install --save-dev cross-envThen add a script such as:
"start:legacy": "cross-env NODE_OPTIONS=--openssl-legacy-provider react-scripts start"Check your existing scripts before making changes, and avoid replacing the entire package.json just to add one command.
The Better Long-Term Fix: Check Webpack and Your Build Tools
The legacy provider is useful for getting an old project running, but it doesn't resolve the underlying incompatibility.
Start by checking your environment:
node -v
npm -vThen inspect the relevant dependencies:
npm ls webpack
npm ls react-scriptsThe second command is relevant if your project uses Create React App. If it doesn't, inspect the build tool your project actually uses.
Older Webpack versions are a common cause of this error. Webpack 5 introduced changes that can avoid this problem, depending on the version and configuration. Updating the build tool or its parent dependency may therefore remove the need for the legacy provider.
However, don't blindly upgrade Webpack in an older project. Your application may rely on a particular configuration, loader, plugin, or framework version. A major upgrade can introduce separate errors that take longer to resolve than the original issue.
Before changing dependencies, inspect the current versions and check which upgrades are compatible with your project. Review the relevant release notes, update in a separate branch, and test both development and production builds.
For a Create React App project, that may mean investigating whether the installed react-scripts version supports a newer Webpack version. Updating react-scripts is often more appropriate than manually forcing a different Webpack version into its dependency tree.
Should You Downgrade Node.js?
Sometimes, yes.
If you're maintaining a legacy project that depends on an older build tool, using a compatible Node.js version can be the most straightforward short-term solution.
First, check whether the repository specifies a Node.js version in a .nvmrc file, a package.json engines field, or its development documentation. A version manager can help you switch between Node.js versions without changing the runtime for every project on your machine.
Avoid downgrading to an obsolete Node.js release for a production system without considering its security-support status. An old runtime may get the build working, but it can leave you with security and compatibility problems later.
For a project that must remain in service, the better plan is to establish a supported Node.js version and update the build tooling to work with it. If you only need to inspect or temporarily maintain an abandoned project, document the version requirement so the next developer doesn't encounter the same surprise.
Why Deleting node_modules Usually Doesn't Fix This
It's tempting to delete node_modules, remove package-lock.json, and reinstall everything. That approach is unlikely to solve an OpenSSL incompatibility by itself.
The error generally comes from how the build tool interacts with the Node.js cryptographic APIs, not simply from corrupted installed files.
Deleting the lockfile can also cause npm to resolve different dependency versions, potentially introducing additional problems.
Instead, preserve the lockfile while diagnosing the error. Check your Node.js version, identify the build tool involved, and test the temporary compatibility option. If you later upgrade dependencies, review the changes and keep the lockfile consistent with package.json.
What If the Error Still Appears?
If the legacy-provider workaround doesn't help, don't assume you entered the command incorrectly and keep repeating it.
Check these details:
- Confirm which Node.js executable is running. Run
node -vin the same terminal where you start the project. - Check the exact command that fails. The development server, production build, and test runner may use different dependencies.
- Look at the complete stack trace. Identify the package or file mentioned immediately before the error.
- Check whether the environment variable is set. In PowerShell, run
echo $env:NODE_OPTIONS; in Command Prompt, runecho %NODE_OPTIONS%. - Check your package manager and lockfile. Avoid mixing npm, Yarn, or pnpm commands without understanding how the project manages dependencies.
If the error originates from a different cryptographic operation or another unsupported dependency, the correct fix may differ. The full stack trace is more useful than guessing based on the error name alone.
The Fix I'd Choose
For a legacy project that needs to run today, try the legacy OpenSSL provider in a single terminal session. If that resolves the issue, use the result as a clue rather than a reason to leave the workaround in place forever.
For a project you actively maintain, identify the outdated build tool and plan a compatible upgrade. For a project tied to a specific Node.js version, document that requirement and use a supported runtime wherever possible.
The important thing is not to change five parts of the project when one targeted adjustment can confirm the cause. Get the application running, verify the result, and then decide whether the workaround or a proper dependency upgrade makes the most sense.
0 Comments