If you're a developer using Webpack in your Rails (or any other) project, you may encounter the following error after upgrading your macOS or Node.js version:

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:68:19)
    at Object.createHash (node:crypto:138:10)

This error can prevent your Rails app (or any Webpack-powered project) from starting, especially if you haven't worked on the project in a while. In this blog post, I'll explain the root cause of the issue, why it happens in Node.js 17+, and how to fix it with a simple workaround.

Understanding the Problem

The error you're seeing is rooted in changes introduced in Node.js 17 and above. Node.js 17 switched from using OpenSSL 1.x to OpenSSL 3, which brings improved security features. While these changes enhance security, they also deprecate older cryptographic algorithms.

Webpack (and some of its plugins) rely on cryptographic functions to perform tasks like content fingerprinting, which involves creating hashes. However, because Webpack might be using algorithms no longer supported by default in OpenSSL 3, Node.js throws the error:0308010C when Webpack tries to create these hashes.

In simpler terms, Node.js 17 and Webpack aren't fully compatible yet due to the way cryptography is handled, and that’s what causes the error.

The Quick Fix: --openssl-legacy-provider

The fastest and most effective way to resolve this issue is by using the --openssl-legacy-provider flag. This tells Node.js to fall back on the cryptographic algorithms from OpenSSL 1.x, which Webpack can handle without throwing errors.

To apply this fix, all you need to do is add an environment variable to your terminal session or script configuration.

Applying the Fix

You can set the NODE_OPTIONS environment variable like this:

export NODE_OPTIONS=--openssl-legacy-provider

This command tells Node.js to enable the legacy OpenSSL provider, bypassing the stricter cryptographic policies introduced in Node.js 17+.

Persistent Fix in package.json

Alternatively, if you want to make this fix persistent for your project, you can add it directly to the scripts section of your package.json file. This way, every time you run Webpack commands, the legacy provider will be used automatically:

"scripts": {
  "start": "NODE_OPTIONS=--openssl-legacy-provider webpack serve"
}

This ensures that no matter where you run your project, Node.js will use the legacy OpenSSL provider, keeping your Webpack build from failing.

Why This Works

The introduction of OpenSSL 3 in Node.js 17 removed support for older cryptographic algorithms that Webpack might still be relying on. By using the --openssl-legacy-provider flag, you instruct Node.js to allow the use of those older algorithms, which are still supported by Webpack.

This enables Webpack to function as it did before the upgrade to Node.js 17, allowing it to generate hashes and handle cryptographic functions without issues.

Checking Your Node.js Version

Before applying any fixes, it’s a good idea to check which version of Node.js you’re using. Run the following command:

node -v

If you’re on Node.js 17 or higher, you’re likely to face this issue. If you prefer not to use the legacy provider flag, an alternative solution is to downgrade to Node.js 16, which uses OpenSSL 1.x and doesn't encounter this problem.

Downgrading Node.js (Optional)

If you don’t want to use the --openssl-legacy-provider workaround, you can instead downgrade to Node.js 16, which will avoid the cryptographic issues entirely. Node.js 16 is a Long-Term Support (LTS) version and will receive security updates until September 2024.

How to Downgrade Node.js

To easily manage multiple Node.js versions, you can use Node Version Manager (NVM):

1. Install NVM (if you don’t have it already):
   

   curl -o- https://raw.githubusercontent.com/nvm- 
   sh/nvm/v0.39.3/install.sh | bash
   source ~/.nvm/nvm.sh
   

2. Install Node.js 16:
   

   nvm install 16
   

3. Switch to Node.js 16:
   

   nvm use 16
   

Once you’re running Node.js 16, Webpack should work without the need for the legacy provider flag.

Long-Term Solutions

While the --openssl-legacy-provider flag is a quick fix, there are long-term solutions you can consider:

1. Upgrade Webpack and Plugins: Webpack and its ecosystem are being actively updated, so it's likely that newer versions will fully support Node.js 17+ and OpenSSL 3 without requiring any workarounds. Be sure to check for updates to Webpack and its plugins and upgrade them when possible.

2. Stick with Node.js 16 for now: If you prefer stability over bleeding-edge updates, sticking with Node.js 16 is a safe bet. It remains an LTS version until 2024, so you'll continue to receive security updates while avoiding these compatibility issues.

Conclusion

The transition to OpenSSL 3 in Node.js 17 has caused some incompatibilities with older cryptographic algorithms that tools like Webpack rely on. By setting the NODE_OPTIONS=--openssl-legacy-provider flag, you can quickly resolve the issue without downgrading Node.js. However, it’s worth keeping an eye on Webpack updates or considering a downgrade to Node.js 16 until full compatibility is achieved.

Hopefully, this post has helped you get your Rails/Webpack project running again. Feel free to reach out with any questions, and happy coding!

References

• Node.js Releases
• Webpack Documentation
• NVM Documentation