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

Upgrading NodeJS can sometimes lead to unexpected errors due to deprecated features or changes in support for cryptographic protocols. After recently upgrading my NodeJS from version 16 to a newer version, my UmiJS projects started producing an error:

error:0308010C:digital envelope routines::unsupported

If you're here for a quick fix, here it is: you can resolve this issue by adding the --openssl-legacy-provider option to your NodeJS configuration. This can be done by setting an environment variable named NODE_OPTIONS:

export NODE_OPTIONS=--openssl-legacy-provider

Or, by including it directly in your package.json scripts:

{
  "scripts": {
    "start": "NODE_OPTIONS=--openssl-legacy-provider node index.js"
  }
}

Now, if you're interested in understanding why this error occurs and how the solution works, let's delve deeper.

Understanding the Problem

The error message "digital envelope routines::unsupported" is related to the use of an outdated or unsupported cryptographic algorithm, commonly known as a "cipher," in NodeJS. As newer versions of NodeJS cease supporting certain outdated ciphers, projects that still rely on these ciphers (like some UmiJS projects) will start producing errors.

Why does --openssl-legacy-provider fix the problem?

Cryptography is an ever-evolving field, with old, potentially insecure ciphers being replaced by newer, more secure ones. The --openssl-legacy-provider option essentially instructs NodeJS to utilize the older OpenSSL provider that still supports these outdated ciphers, hence circumventing the issue at hand.

Integrating the solution into your package.json

While the first solution I presented sets the NODE_OPTIONS environment variable for your entire system, you might prefer a more project-specific solution. This is where the package.json scripts come in.

By modifying your start script as shown above, you ensure that NodeJS uses the legacy OpenSSL provider each time you run your project, regardless of the global NodeJS settings. This can be especially useful if you're working with multiple NodeJS projects that might require different configurations.

---

Upgrading your software is usually a good practice as it brings new features and improvements, but sometimes it can cause unforeseen issues due to changes in the underlying systems. When you encounter such issues, knowing how to troubleshoot and find workarounds can be invaluable. Stay curious and keep coding!