# Resolving `ERR_OSSL_EVP_UNSUPPORTED` in Node.js

## Problem Statement

When upgrading to Node.js version 18 or later, you may encounter this cryptographic error:

opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ], library: 'digital envelope routines', reason: 'unsupported', code: 'ERR_OSSL_EVP_UNSUPPORTED'

**Key characteristics:**
- Occurs specifically in Node.js ≥v17 after upgrading
- Affects applications using older cryptographic libraries (common in React projects)
- Triggered by Node.js 18's default OpenSSL 3 configuration, which restricts legacy algorithms
- Frequently seen with `react-scripts` during `npm start` or `npm build`

::: warning Security Note
Legacy cryptographic algorithms have known vulnerabilities. Permanent workarounds should only be used when immediate dependency updates aren't feasible.
:::

## Recommended Solutions

### 1. Update `react-scripts` (Recommended Permanent Fix)

Updating your React dependencies is the secure, forward-compatible solution:

```bash
# Update react-scripts to latest compatible version
npm install react-scripts@latest

# Verify updates in package.json
npm list react-scripts

Why this works:
Recent react-scripts versions use modern cryptography standards compliant with OpenSSL 3.

2. Enable Legacy OpenSSL Provider (Temporary Workaround)

Modify your package.json scripts to enable legacy support:

// In package.json
"scripts": {
  "start": "react-scripts --openssl-legacy-provider start",
  "build": "react-scripts --openssl-legacy-provider build"
}

Note: This should be a temporary measure. Verify functionality with:

npm run start

3. Environment Variable Workaround (Quick Temporary Fix)

Set the legacy option session-wide via terminal:

::: code-group-item Linux/macOS

bash

export NODE_OPTIONS=--openssl-legacy-provider

::: ::: code-group-item Windows (Command Prompt)

bash

set NODE_OPTIONS=--openssl-legacy-provider

::: ::: code-group-item Windows (PowerShell)

powershell

$env:NODE_OPTIONS = "--openssl-legacy-provider"

:::

This persists only for the current terminal session.

4. Update All Dependencies (Comprehensive Upgrade)

For outdated projects, systematic dependency updates may be needed:

# Install update helper
npm install -g npm-check-updates

# Check updatable packages
ncu

# Update package.json
ncu -u

# Install updates
npm install

Solution Comparison

Solution	Security	Permanence	Complexity
Update react-scripts	✅ Secure	Permanent	Low
Update All Dependencies	✅ Secure	Permanent	Medium
Environment Variable	⚠️ Insecure	Temporary	Low
Legacy Flag in Scripts	⚠️ Insecure	Temporary	Low
Node.js Downgrade	❌ Risky	Temporary	High

Avoid This Outdated Approach

Downgrading Node.js (e.g., to v16) provides immediate relief but:

• Deprecates security patches
• Postpones inevitable updates
• Increases technical debt

# Not recommended
nvm install 16.20.2
nvm use 16

Best Practices

1. Prioritize dependency updates over workarounds for long-term security
2. Test solutions in non-production environments first
3. Remove temporary fixes (--openssl-legacy-provider) once dependencies are updated
4. Verify Node.js compatibility with:

   node -v # v18 or newer preferred

5. Monitor dependencies with npm audit to prevent similar issues

Always default to dependency updates as your primary solution, reserving OpenSSL legacy flags only for short-term contingencies during migration.