Khi làm việc với Node.js, đặc biệt là sau khi nâng cấp lên các phiên bản 17 trở lên, nhiều nhà phát triển đã gặp phải lỗi ERR_OSSL_EVP_UNSUPPORTED. Đây là một lỗi phổ biến liên quan đến thư viện mã hóa OpenSSL, gây cản trở quá trình phát triển và triển khai ứng dụng. Bài viết này sẽ đi sâu vào tìm hiểu bản chất của lỗi, phân tích các nguyên nhân chính và cung cấp những giải pháp khắc phục hiệu quả nhất.
🔑 Lỗi ERR_OSSL_EVP_UNSUPPORTED là gì?
Đây là lỗi liên quan đến thư viện mã hóa OpenSSL, thường xuất hiện khi ứng dụng cố gắng sử dụng các thuật toán hoặc kích thước khóa không còn được hỗ trợ bởi phiên bản OpenSSL hiện tại (đặc biệt là OpenSSL 3.0 trở lên).
💡 Nguyên nhân chính gây lỗi
Lỗi này phổ biến do Node.js v17+ chuyển sang OpenSSL 3.0, vốn đã loại bỏ các thuật toán cũ, kém an toàn. Cụ thể:
- Nâng cấp Node.js lên v17+: Node.js mới dùng OpenSSL 3.0, không tương thích ngược với các thuật toán cũ.
- Gói phụ thuộc (dependencies) hoặc mã nguồn cũ: Các thư viện bên thứ ba (như Webpack, Babel) hoặc code của bạn vẫn dùng thuật toán mã hóa lỗi thời (MD4, MD5).
- Xung đột môi trường OpenSSL: Không nhất quán phiên bản trong Docker, CI/CD, hoặc cài đặt OpenSSL bị lỗi.
🛠️ Cách sửa lỗi hiệu quả
- Sử dụng Legacy OpenSSL Provider (Giải pháp nhanh, tạm thời): Thêm `NODE_OPTIONS=–openssl-legacy-provider` vào script `start` hoặc `build` trong `package.json`.
- Cập nhật các gói phụ thuộc (Giải pháp tốt nhất, lâu dài): Cập nhật Node.js lên phiên bản LTS mới nhất. Chạy `npm update` hoặc `yarn upgrade` để làm mới tất cả dependencies.
- Hạ cấp Node.js xuống v16 (Ổn định, ngắn hạn): Sử dụng `nvm` để chuyển sang Node.js v16 (`nvm install 16`, `nvm use 16`).
- Sửa đổi cấu hình Webpack (Nếu lỗi do Webpack): Trong `webpack.config.js`, đặt `output.hashFunction: ‘sha256’`.
- Sử dụng Docker với phiên bản phù hợp: Dùng Docker image Node.js cũ hơn (ví dụ: `node:16-alpine`). Hoặc thêm `ENV NODE_OPTIONS=”–openssl-legacy-provider”` vào Dockerfile.
🛡️ Phòng tránh lỗi tái diễn
- Luôn cập nhật Node.js LTS.
- Kiểm tra và cập nhật định kỳ các gói phụ thuộc.
- Đảm bảo môi trường phát triển và triển khai nhất quán.
- Hạn chế dùng `–openssl-legacy-provider` trong môi trường sản xuất.
Việc hiểu rõ nguyên nhân sẽ giúp bạn giải quyết lỗi `ERR_OSSL_EVP_UNSUPPORTED` một cách hiệu quả và bền vững!
1. ERR_OSSL_EVP_UNSUPPORTED là lỗi gì?
Lỗi ERR_OSSL_EVP_UNSUPPORTED là lỗi xảy ra khi một ứng dụng hoặc module cố gắng sử dụng thuật toán mật mã hoặc kích thước khóa không còn được hỗ trợ hoặc bị hạn chế theo mặc định trong phiên bản OpenSSL đang được sử dụng. Đây là một lỗi liên quan đến thư viện mã hóa OpenSSL.
Nói một cách đơn giản: Bạn có một chiếc két sắt cũ (ứng dụng của bạn) và một chiếc chìa khóa cũ để mở nó (thuật toán mã hóa cũ). Bây giờ, bạn nâng cấp chiếc két sắt lên một phiên bản siêu hiện đại, an toàn hơn rất nhiều (thư viện OpenSSL 3.0). Chiếc két mới này được thiết kế để chỉ chấp nhận những loại chìa khóa mới, hiện đại hơn, vì những chiếc chìa khóa cũ không còn đủ an toàn nữa.
Lỗi ERR_OSSL_EVP_UNSUPPORTED xảy ra khi bạn cố gắng dùng chiếc chìa khóa cũ (thuật toán mã hóa cũ, không còn an toàn) để mở chiếc két sắt mới (ứng dụng đang chạy với OpenSSL 3.0). Và nó báo lỗi để bạn biết rằng bạn cần dùng một loại chìa khóa an toàn hơn.

Xem thêm: Lỗi ERR_HTTP2_PROTOCOL_ERROR là gì và cách sửa lỗi?
2. Tại sao lỗi ERR_OSSL_EVP_UNSUPPORTED lại phổ biến?
Lỗi ERR_OSSL_EVP_UNSUPPORTED phổ biến là kết quả của việc Node.js v17+ chuyển sang OpenSSL 3.0, trong khi OpenSSL 3.0 đã chủ động loại bỏ hoặc hạn chế các thuật toán mật mã cũ, kém an toàn. Điều này gây ra sự không tương thích với các ứng dụng và thư viện Node.js hiện có mà vẫn đang sử dụng hoặc phụ thuộc vào các thuật toán đã bị loại bỏ.
3. Nguyên nhân chính gây ra lỗi ERR_OSSL_EVP_UNSUPPORTED
Lỗi ERR_OSSL_EVP_UNSUPPORTED chủ yếu phát sinh khi môi trường được nâng cấp lên Node.js phiên bản 17 trở lên, trong khi các gói phụ thuộc hoặc mã nguồn của dự án vẫn chưa được cập nhật để tương thích. Sự không đồng bộ này gây ra xung đột vì phiên bản OpenSSL 3.0 mới trong Node.js đã ngừng hỗ trợ các thuật toán mã hóa cũ, vốn vẫn đang được yêu cầu bởi những thư viện lỗi thời đó. Cụ thể:
3.1. Nâng cấp Node.js lên phiên bản 17 trở lên
Đây là nguyên nhân phổ biến nhất. Kể từ Node.js phiên bản 17, môi trường runtime này đã chuyển sang sử dụng OpenSSL 3.0 làm thư viện mật mã cơ bản, thay thế cho OpenSSL 1.1.1 của các phiên bản Node.js trước đó.
- Thay đổi trong OpenSSL 3.0: OpenSSL 3.0 được thiết kế với mục tiêu tăng cường bảo mật và hiện đại hóa. Để đạt được điều này, nó đã loại bỏ hoặc hạn chế hỗ trợ cho một số thuật toán mã hóa cũ, kém an toàn (ví dụ: MD4, MD5) và các phương thức mật mã đã lỗi thời. Các thuật toán này không còn được coi là phù hợp cho các ứng dụng yêu cầu mức độ bảo mật cao.
- Không tương thích ngược: Khi một dự án được phát triển trên phiên bản Node.js cũ (sử dụng OpenSSL 1.1.1) và sau đó được chạy trên Node.js 17+, nếu code hoặc các thư viện phụ thuộc vẫn cố gắng sử dụng các thuật toán đã bị loại bỏ, lỗi ERR_OSSL_EVP_UNSUPPORTED sẽ xuất hiện.
3.2. Các gói phụ thuộc hoặc mã nguồn chưa được cập nhật
Ngay cả khi bạn đã nâng cấp Node.js, lỗi ERR_OSSL_EVP_UNSUPPORTED vẫn có thể xảy ra nếu các thành phần khác trong dự án của bạn không theo kịp.
- Thư viện bên thứ ba cũ: Nhiều thư viện JavaScript, đặc biệt là trong các dự án front-end (React, Next.js, Vue.js) hoặc các công cụ xây dựng (build tools) như Webpack, Babel, có thể có các phụ thuộc nội bộ vào các thuật toán mã hóa cũ. Ví dụ, một số phiên bản Webpack cũ sử dụng thuật toán MD4 hoặc MD5 để tạo hàm băm (hash) cho các module hoặc tài sản. Khi chạy với OpenSSL 3.0, các hoạt động này sẽ thất bại.
- Mã nguồn ứng dụng cũ: Nếu mã nguồn ứng dụng của bạn trực tiếp gọi các hàm mật mã đã lỗi thời hoặc sử dụng các cấu hình không còn được hỗ trợ bởi OpenSSL 3.0, lỗi ERR_OSSL_EVP_UNSUPPORTED sẽ phát sinh. Điều này ít phổ biến hơn trong các ứng dụng thông thường nhưng có thể xảy ra trong các hệ thống chuyên biệt về mật mã.
- Chuỗi công cụ (toolchain) phức tạp: Trong các dự án hiện đại, có rất nhiều lớp trừu tượng và các gói phụ thuộc. Việc xác định chính xác gói nào đang gây ra vấn đề có thể khó khăn, đặc biệt nếu nó là một phụ thuộc của một phụ thuộc khác.
Xem thêm: Lỗi ERR_SSL_PROTOCOL_ERROR: Nguyên nhân và cách sửa
3.3. Xung đột phiên bản OpenSSL trong môi trường
Trong một số trường hợp, lỗi ERR_OSSL_EVP_UNSUPPORTED có thể không chỉ do Node.js mà còn do môi trường hoạt động.
- Môi trường Docker hoặc CI/CD: Nếu bạn đang triển khai ứng dụng trong môi trường container (Docker) hoặc các hệ thống Tích hợp liên tục/Triển khai liên tục (CI/CD), có thể có sự không nhất quán về phiên bản OpenSSL giữa docker image cơ sở, Node.js được cài đặt và các thư viện hệ thống.
- Cài đặt OpenSSL bị lỗi/không đúng: Trong một số ít trường hợp, việc cài đặt OpenSSL trên hệ điều hành có thể bị hỏng, thiếu các module cần thiết hoặc có cấu hình không chuẩn, dẫn đến việc không thể cung cấp các thuật toán ngay cả khi chúng được hỗ trợ.
- Biến môi trường: Đôi khi, các biến môi trường cấu hình OpenSSL (ví dụ: OPENSSL_CONF) có thể trỏ đến một tệp cấu hình không hợp lệ hoặc giới hạn các thuật toán được phép, gây ra lỗi ERR_OSSL_EVP_UNSUPPORTED.

4. Cách sửa lỗi ERR_OSSL_EVP_UNSUPPORTED nhanh chóng, hiệu quả
Để khắc phục nhanh lỗi ERR_OSSL_EVP_UNSUPPORTED, bạn có thể áp dụng các giải pháp tạm thời như hạ cấp Node.js xuống v16 hoặc kích hoạt Legacy OpenSSL Provider nhằm cho phép các thuật toán cũ hoạt động. Tuy nhiên, phương pháp giải quyết triệt để và an toàn nhất là cập nhật các gói phụ thuộc của dự án hoặc điều chỉnh cấu hình Webpack và OpenSSL của hệ thống để đảm bảo tương thích hoàn toàn với các tiêu chuẩn bảo mật mới. Cách sửa lỗi cụ thể như sau:
4.1. Cài đặt Legacy OpenSSL Provider cho Node.js (Khắc phục nhanh nhất)
Đây là giải pháp tức thời và phổ biến nhất, đặc biệt khi bạn không thể cập nhật ngay lập tức các gói phụ thuộc cũ. Nó yêu cầu Node.js cho phép sử dụng các thuật toán OpenSSL cũ hơn.
Cách thực hiện: Bạn có thể đặt biến môi trường NODE_OPTIONS trước khi chạy lệnh Node.js của mình.
Trong package.json (phổ biến cho các dự án web như React, Next.js): Bạn thêm NODE_OPTIONS=–openssl-legacy-provider vào đầu các script start hoặc build của mình.
“scripts”: {
“start”: “NODE_OPTIONS=–openssl-legacy-provider react-scripts start”,
“build”: “NODE_OPTIONS=–openssl-legacy-provider react-scripts build”
}
Nếu bạn đang sử dụng Windows, cú pháp sẽ khác một chút:
“scripts”: {
“start”: “set NODE_OPTIONS=–openssl-legacy-provider && react-scripts start”,
“build”: “set NODE_OPTIONS=–openssl-legacy-provider && react-scripts build”
}
Khi chạy lệnh trực tiếp từ terminal:
export NODE_OPTIONS=–openssl-legacy-provider
npm run start
Hoặc trên Windows:
set NODE_OPTIONS=–openssl-legacy-provider && npm run start
- Ưu điểm: Giải quyết lỗi ERR_OSSL_EVP_UNSUPPORTED ngay lập tức mà không cần thay đổi code hoặc cập nhật các gói phụ thuộc lớn.
- Nhược điểm: Đây chỉ là giải pháp tạm thời. Nó làm giảm mức độ bảo mật bằng cách kích hoạt lại các thuật toán cũ, kém an toàn. Mục tiêu lâu dài là loại bỏ sự phụ thuộc vào các thuật toán này.
4.2. Cập nhật các gói phụ thuộc (Giải pháp tốt nhất và lâu dài)
Đây là cách tiếp cận được khuyến nghị để giải quyết triệt để lỗi ERR_OSSL_EVP_UNSUPPORTED, vì nó đảm bảo dự án của bạn sử dụng các tiêu chuẩn bảo mật hiện đại.
Cách thực hiện:
- Cập nhật Node.js: Đảm bảo bạn đang sử dụng phiên bản Node.js LTS (Long Term Support) mới nhất.
- Cập nhật npm hoặc yarn: npm install -g npm@latest hoặc yarn set version stable.
- Cập nhật tất cả các gói phụ thuộc trong dự án: Chạy npm update hoặc yarn upgrade trong thư mục dự án của bạn. Đối với các dự án React, Next.js, Vue.js, hãy đặc biệt chú ý cập nhật các gói như react-scripts, webpack, babel-loader và các plugin/loader liên quan đến webpack lên phiên bản tương thích với OpenSSL 3.0. Trong một số trường hợp, bạn có thể cần kiểm tra npm audit hoặc yarn audit để tìm các lỗ hổng bảo mật và chạy npm audit fix –force để cố gắng khắc phục chúng.
- Ưu điểm: Khắc phục nguyên nhân gốc rễ của vấn đề, nâng cao bảo mật cho ứng dụng và đảm bảo tương thích với các công nghệ mới nhất.
- Nhược điểm: Có thể tốn thời gian và công sức, đặc biệt với các dự án lớn có nhiều gói phụ thuộc và có thể gặp phải các lỗi tương thích khác sau khi cập nhật.
4.3. Hạ cấp Node.js xuống v16 (Phiên bản LTS ổn định)
Nếu bạn gặp khó khăn trong việc cập nhật các gói phụ thuộc hoặc cần một giải pháp ổn định hơn trong thời gian ngắn mà không muốn sử dụng legacy-provider.
- Cách thực hiện: Sử dụng một công cụ quản lý phiên bản Node.js như nvm (Node Version Manager) để chuyển đổi phiên bản:
- Cài đặt nvm (nếu chưa có)
- Cài đặt Node.js 16: nvm install 16
- Chuyển sang sử dụng Node.js 16: nvm use 16
- Xác minh: node -v
- Ưu điểm: Đảm bảo khả năng tương thích với các thư viện cũ không hỗ trợ OpenSSL 3.0 mà không cần bật legacy-provider. Node.js 16 là phiên bản LTS và rất ổn định.
- Nhược điểm: Bạn không được hưởng lợi từ các cải tiến và tính năng mới nhất trong Node.js 17+ và OpenSSL 3.0. Đây cũng chỉ là một giải pháp tạm thời, không phải là giải pháp bền vững cho việc hiện đại hóa ứng dụng.
4.4. Sửa đổi cấu hình Webpack (Nếu lỗi cụ thể do Webpack)
Nếu lỗi ERR_OSSL_EVP_UNSUPPORTED xuất hiện rõ ràng khi Webpack đang xây dựng (build) dự án của bạn, đặc biệt liên quan đến MD4/MD5, bạn có thể cấu hình Webpack để sử dụng thuật toán băm (hash algorithm) khác.
- Cách thực hiện: Trong tệp cấu hình webpack.config.js của bạn, thêm hoặc sửa đổi thuộc tính output.hashFunction hoặc output.hashAlgorithm để sử dụng thuật toán SHA256.
module.exports = {
// …
output: {
// …
hashFunction: ‘sha256’, // hoặc hashAlgorithm: ‘sha256’ tùy theo phiên bản webpack
// Nếu bạn thấy lỗi liên quan đến crypto-browserify:
// resolve: {
// fallback: {
// “crypto”: require.resolve(“crypto-browserify”)
// }
// }
},
// …
};
- Nếu bạn không thể tìm thấy output.hashFunction hoặc output.hashAlgorithm, hãy kiểm tra tài liệu của phiên bản Webpack bạn đang sử dụng. Đôi khi, lỗi cũng có thể liên quan đến việc Webpack cần polyfill cho module crypto trong trình duyệt; trong trường hợp đó, phần resolve.fallback có thể hữu ích.
- Ưu điểm: Giải quyết vấn đề trực tiếp trong Webpack mà không cần thay đổi môi trường Node.js.
- Nhược điểm: Chỉ giải quyết được vấn đề nếu Webpack là nguyên nhân duy nhất và không phải là giải pháp chung cho các lỗi khác liên quan đến OpenSSL.
4.5. Sửa đổi cấu hình OpenSSL của hệ thống (Cho người dùng nâng cao)
Đây là một giải pháp ít phổ biến và không khuyến khích cho hầu hết người dùng, vì nó liên quan đến việc thay đổi cấu hình OpenSSL toàn hệ thống và có thể ảnh hưởng đến các ứng dụng khác. Chỉ nên xem xét nếu bạn hiểu rõ về OpenSSL và biết chính xác điều mình đang làm.
- Cách thực hiện: Bạn có thể chỉnh sửa tệp cấu hình OpenSSL (ví dụ: openssl.cnf trên Linux/macOS hoặc openssl.cfg trên Windows) để kích hoạt lại các thuật toán cũ. Điều này thường được thực hiện bằng cách thêm dòng default_modules = providers và [providers] sau đó default = default_sect và legacy = legacy_sect và cuối cùng là [legacy_sect] activate = 1.
- Tìm tệp cấu hình OpenSSL: Đường dẫn thường là /etc/ssl/openssl.cnf trên Linux hoặc trong thư mục cài đặt OpenSSL trên Windows.
Thêm các dòng sau vào cuối tệp:
[ssl_sect]
system_default = system_default_sect
[system_default_sect]
# Bật các nhà cung cấp cũ
Providers = default,legacy
- Ưu điểm: Cung cấp giải pháp toàn hệ thống.
- Nhược điểm: Rủi ro cao về bảo mật (vì nó kích hoạt các thuật toán kém an toàn trên toàn hệ thống). Không được khuyến khích trừ khi bạn có lý do rất cụ thể và được kiểm soát chặt chẽ.
4.6. Sử dụng Docker với phiên bản OpenSSL hoặc Node.js phù hợp (Dành cho ứng dụng được chứa trong container)
Nếu ứng dụng của bạn được triển khai trong Docker container, bạn có thể kiểm soát môi trường một cách chính xác.
- Cách thực hiện:
- Sử dụng Node.js image cũ hơn: Thay đổi Dockerfile của bạn để sử dụng một phiên bản Node.js dưới 17 (ví dụ: node:16-alpine hoặc node:16-lts).
- Đặt biến môi trường trong Dockerfile: Nếu bạn muốn sử dụng Node.js 17+ nhưng vẫn cần legacy-provider, hãy thêm biến môi trường vào Dockerfile:
FROM node:18-alpine
ENV NODE_OPTIONS=”–openssl-legacy-provider”
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD [“npm”, “start”]
- Ưu điểm: Kiểm soát chặt chẽ môi trường runtime, đảm bảo tính nhất quán giữa các môi trường phát triển và triển khai.
- Nhược điểm: Yêu cầu kiến thức về Docker và có thể cần xây dựng lại hình ảnh container.

5. Biện pháp phòng tránh lỗi ERR_OSSL_EVP_UNSUPPORTED tái diễn
Để phòng tránh lỗi ERR_OSSL_EVP_UNSUPPORTED tái diễn trong các dự án Node.js, bạn cần áp dụng các biện pháp chủ động trong quá trình phát triển và bảo trì. Các biện pháp này tập trung vào việc duy trì môi trường phát triển và các gói phụ thuộc (dependencies) luôn được cập nhật và tương thích.
- Luôn cập nhật Node.js lên phiên bản LTS mới nhất: Node.js LTS (Long Term Support) là các phiên bản được khuyến nghị cho môi trường sản xuất vì chúng nhận được sự hỗ trợ và cập nhật bảo mật liên tục trong thời gian dài.
- Định kỳ cập nhật và kiểm tra các gói phụ thuộc (dependencies): Đây là biện pháp quan trọng nhất để đảm bảo các thư viện mà dự án của bạn sử dụng tương thích với phiên bản Node.js và OpenSSL mới nhất.
- Kiểm soát môi trường phát triển và triển khai: Đảm bảo môi trường mà ứng dụng của bạn chạy nhất quán và được quản lý tốt.
- Hạn chế sử dụng biến môi trường –openssl-legacy-provider trong môi trường sản xuất: Mặc dù NODE_OPTIONS=–openssl-legacy-provider là một giải pháp khắc phục nhanh, nó không phải là giải pháp bền vững.
6. Câu hỏi thường gặp về lỗi ERR_OSSL_EVP_UNSUPPORTED
6.1. Tại sao openssl-legacy-provider chỉ là giải pháp tạm thời?
Nó cho phép sử dụng lại các thuật toán mã hóa cũ, kém an toàn đã bị OpenSSL 3.0 loại bỏ. Điều này làm giảm mức độ bảo mật của ứng dụng, khiến nó dễ bị tấn công hơn.
6.2. Hạ cấp Node.js có ảnh hưởng gì đến hiệu suất/bảo mật không?
- Hiệu suất: Thường không có ảnh hưởng đáng kể đến hiệu suất tổng thể, nhưng bạn sẽ không được hưởng lợi từ các tối ưu hóa mới nhất của Node.js 17+.
- Bảo mật: Bạn có thể bỏ lỡ các bản vá bảo mật và cải tiến từ các phiên bản Node.js và OpenSSL mới hơn, nhưng sẽ tránh được lỗi ERR_OSSL_EVP_UNSUPPORTED nếu các dependencies cũ vẫn còn.
6.3. Làm thế nào để biết dependencies nào đang gây ra lỗi?
Kiểm tra stack trace của lỗi: Nó thường chỉ ra file và module nào đang gọi hàm mật mã không được hỗ trợ. Tìm kiếm các gói liên quan đến crypto, hashing (ví dụ: MD4, MD5), hoặc các công cụ build như Webpack trong stack trace.
6.4. Lỗi này có xảy ra trên các môi trường production không?
Có. Nếu môi trường production của bạn sử dụng Node.js phiên bản 17 trở lên và các gói phụ thuộc của ứng dụng chưa được cập nhật tương thích với OpenSSL 3.0, lỗi ERR_OSSL_EVP_UNSUPPORTED sẽ xuất hiện.
Lỗi ERR_OSSL_EVP_UNSUPPORTED là một thách thức phổ biến mà các nhà phát triển Node.js thường gặp phải khi chuyển đổi sang các phiên bản Node.js 17+ do sự thay đổi sang OpenSSL 3.0 với các tiêu chuẩn bảo mật nghiêm ngặt hơn. Việc hiểu rõ nguyên nhân gốc rễ sẽ là chìa khóa để giải quyết vấn đề.
Mặc dù lỗi ERR_OSSL_EVP_UNSUPPORTED không trực tiếp gây ra bởi chứng chỉ SSL mà do xung đột thuật toán trong môi trường lập trình, nó nhấn mạnh tầm quan trọng sống còn của việc sử dụng các giao thức mã hóa hiện đại và hợp lệ. Vì vậy, để đảm bảo an toàn tuyệt đối cho website và tạo dựng niềm tin nơi khách hàng, hãy trang bị ngay chứng chỉ SSL uy tín như Sectigo SSL hoặc GeoTrust SSL với chi phí tối ưu tại VinaHost để bảo vệ dữ liệu người dùng một cách chuyên nghiệp.
Tìm hiểu thêm nhiều bài viết khác TẠI ĐÂY hoặc liên hệ với VinaHost qua:
- Email: support@vinahost.vn
- Hotline: 1900 6046
- Livechat: https://livechat.vinahost.vn/chat.php
Xem ngay các bài viết liên quan:
Cách sửa lỗi SSL Certificate Problem Unable to Get Local Issuer Certificate