ERR_SSL_CIPHER_OPERATION_FAILED menunjukkan operasi kriptografi pada koneksi TLS gagal. Kode ini saja tidak cukup untuk menyimpulkan penyebabnya: perlu pesan OpenSSL lengkap, versi Node.js, tujuan koneksi, dan jalur proxy. Jangan menyamakannya dengan error sertifikat atau unsafe legacy renegotiation disabled.

Pertahankan HTTPS dan verifikasi sertifikat. Tidak perlu mematikan antivirus, firewall, atau mengganti registry menjadi HTTP untuk melakukan diagnosis awal.

Batas pengujian: fixture HTTPS loopback pada Node.js 24.12.0/npm 11.6.2 menolak CA yang belum dipercaya, lalu menghasilkan PONG dengan CA uji eksplisit dan strict-ssl=true. Itu hanya menguji trust CA; bukan reproduksi ERR_SSL_CIPHER_OPERATION_FAILED, uji registry nyata, atau bukti instalasi proyek berhasil. Versi tersebut adalah runtime fixture, bukan rekomendasi patch terbaru.

Bedakan pesan error yang muncul

Contoh ringkas ini hanya menunjukkan kode, bukan rekaman kasus nyata:

Pesan error Penyebab umum Tindakan yang tepat
ERR_SSL_CIPHER_OPERATION_FAILED Handshake TLS gagal — versi OpenSSL/Node atau proxy Periksa versi Node dan konfigurasi proxy
unsafe legacy renegotiation disabled Server/proxy lama tidak mendukung renegosiasi aman Perbaiki sisi server/proxy, bukan klien
SELF_SIGNED_CERT_IN_CHAIN Rantai sertifikat berisi CA yang tidak dipercaya Pasang CA resmi — jangan matikan verifikasi
ERR_TLS_CERT_ALTNAME_INVALID Nama host tidak cocok dengan sertifikat Cek URL registry dan jam sistem 
npm ERR! code ERR_SSL_CIPHER_OPERATION_FAILED
npm ERR! request to https://registry.npmjs.org/... failed
  • ERR_SSL_CIPHER_OPERATION_FAILED / cipher operation failed: operasi cipher/TLS gagal; korelasikan runtime, log, proxy, serta reproduksi pada environment bersih.
  • unsafe legacy renegotiation disabled: peer tidak mendukung secure renegotiation yang disyaratkan klien. Error dapat muncul pada handshake awal, bukan bukti bahwa peer baru saja meminta renegosiasi. Perbaiki server/proxy; ini bukan sinonim kegagalan cipher.
  • SELF_SIGNED_CERT_IN_CHAIN atau UNABLE_TO_VERIFY_LEAF_SIGNATURE: rantai sertifikat atau CA yang dipercaya tidak sesuai.
  • ERR_TLS_CERT_ALTNAME_INVALID atau sertifikat kedaluwarsa: periksa nama host, masa berlaku, jam sistem, dan sertifikat endpoint.
  • ERR_OSSL_EVP_UNSUPPORTED saat build: operasi/algoritma crypto tidak didukung; bukan otomatis masalah transport npm.

OpenSSL legacy provider adalah penyedia algoritma lama. Flag --openssl-legacy-provider tidak sama dengan mengizinkan legacy renegotiation dan bukan obat universal error TLS npm. Jangan menjadikannya konfigurasi permanen atau menambahkan flag itu untuk menghindari diagnosis.

1. Kumpulkan versi dan konfigurasi yang relevan

Perintah berikut tidak menginstal paket atau mengubah konfigurasi:

node --version
npm --version
node -p "process.versions.openssl"
npm config get strict-ssl
npm config get registry
npm config get cafile

strict-ssl seharusnya bernilai true. Jika nilainya false, cari pengaturan yang menimpanya di .npmrc proyek/pengguna/global atau environment, lalu perbaiki di sumber konfigurasi dengan persetujuan pemiliknya. Flag --strict-ssl=true pada perintah diagnosis di bawah membuat verifikasi eksplisit, tetapi juga pastikan tidak ada bypass di level runtime.

Periksa secara privat apakah NODE_OPTIONS, NODE_TLS_REJECT_UNAUTHORIZED, NODE_EXTRA_CA_CERTS, HTTP_PROXY, dan HTTPS_PROXY terpasang. Nilai proxy bisa mengandung kredensial. Hindari menempelkan output seluruh environment, npm config list, .npmrc, atau debug log ke forum. Redaksi token, Authorization header, URL berkredensial, nama internal, dan path pengguna sebelum berbagi.

Catat apakah kegagalan terjadi saat npm ping, pengambilan metadata, unduhan tarball, atau lifecycle script. Script paket dapat memakai host dan klien HTTP lain; memperbaiki koneksi registry saja belum membuktikan semua jalur itu sehat.

2. Uji koneksi tanpa menjalankan instalasi

Untuk proyek yang memang memakai registry publik, jalankan:

npm ping --registry=https://registry.npmjs.org/ --strict-ssl=true

Untuk registry privat, gunakan endpoint HTTPS yang disetujui organisasi; jangan mengalihkan paket privat ke registry publik. npm ping menguji endpoint ping/autentikasi registry, bukan mengeksekusi kode paket. Hasil sukses biasanya menampilkan PONG dengan waktu respons dan exit code 0; format output dapat berbeda menurut versi npm. Respons 401/403 mengarah ke otorisasi, bukan otomatis kegagalan cipher.

Jika hanya jaringan tertentu yang gagal, minta tim jaringan membandingkan jalur proxy dan log pada waktu yang sama. Uji melalui jaringan lain hanya bila kebijakan organisasi mengizinkannya; jangan melewati proxy wajib atau mengirim token privat ke endpoint publik. Nama penerbit sertifikat publik dapat berubah, jadi issuer selain nama tertentu bukan bukti tunggal intersepsi.

3. Tangani CA hanya jika ada bukti masalah kepercayaan

Menambahkan CA tidak memperbaiki semua kegagalan cipher. Lakukan ini hanya jika organisasi memang mengoperasikan proxy inspeksi TLS atau registry dengan CA privat, dan log menunjukkan rantai kepercayaan yang sesuai.

Minta bundle CA format PEM dari administrator melalui kanal terverifikasi. Konfirmasi fingerprint lewat kanal terpisah yang dipercaya. Jangan mempercayai sertifikat yang diperoleh dari koneksi gagal semata-mata karena koneksi tersebut mengirimkannya. CA baru memperluas pihak yang dapat dipercaya untuk koneksi TLS.

Untuk pengujian satu kali, gunakan file CA yang disetujui tanpa menulis konfigurasi global. Contoh Bash (ganti path):

npm ping --registry=https://registry.npmjs.org/ --strict-ssl=true --cafile="/path/to/approved-ca-bundle.pem"

Contoh Windows PowerShell:

npm ping --registry=https://registry.npmjs.org/ --strict-ssl=true --cafile="C:/certs/approved-ca-bundle.pem"

Bundle harus sesuai rantai sertifikat yang dipakai endpoint pada jalur itu. cafile dapat menentukan daftar CA secara eksplisit; jangan menganggapnya selalu ditambahkan ke semua CA bawaan. Alternatif Node.js adalah NODE_EXTRA_CA_CERTS, yang menambahkan CA saat proses dimulai, tetapi tidak dipakai ketika opsi ca eksplisit ditentukan oleh klien. Hindari mencampur konfigurasi tanpa memahami prioritasnya.

Setelah verifikasi sukses, administrator dapat memasang konfigurasi berlingkup tepat sesuai kebijakan. Perintah sekali jalan di atas tidak meninggalkan pengaturan npm baru. Jika CA uji tidak diperlukan lagi, jangan mempertahankan trust tambahan.

4. Perbaiki runtime atau endpoint yang bermasalah

Gunakan rilis Node.js LTS yang masih didukung dengan patch keamanan terkini yang kompatibel dengan proyek. Cocokkan dengan engines dan versi yang dipakai CI. Jangan downgrade ke Node.js 16 yang sudah EOL. Versi OpenSSL 3 sendiri bukan bukti penyebab error; catat versi patch dan coba reproduksi minimal pada runtime yang didukung.

Jika log benar-benar menunjukkan unsafe legacy renegotiation, administrator harus memperbarui proxy/registry dan konfigurasi TLS endpoint. Jika masalah muncul pada proxy inspeksi atau agen keamanan, kumpulkan bukti untuk vendor/administrator. Jangan menonaktifkan HTTPS scanning atau kontrol keamanan sebagai langkah umum.

Jika kode tetap ERR_SSL_CIPHER_OPERATION_FAILED, lampirkan reproduksi minimal tanpa kredensial, versi runtime/OpenSSL, endpoint publik yang aman bila relevan, dan perbandingan jaringan/runtime. Jangan memastikan “CA salah” hanya karena suatu percobaan lain kebetulan berhasil.

5. Validasi dependensi pada salinan proyek

Setelah ping/TLS sehat, gunakan salinan proyek atau checkout sementara yang tepercaya, bukan direktori kerja aktif. Tinjau package.json, lockfile, URL registry, dan referensi Git terlebih dahulu. Jangan hapus lockfile untuk memperbaiki transport TLS.

npm ci --ignore-scripts --no-audit --no-fund --strict-ssl=true
npm ls --depth=0

npm ci membutuhkan lockfile yang konsisten dan akan mengganti node_modules di direktori tersebut. --ignore-scripts mencegah lifecycle script instalasi berjalan; ia bukan sandbox menyeluruh dan tidak menjamin semua paket aman. --no-audit --no-fund mengurangi aktivitas tambahan, bukan memperbaiki TLS. Jalankan di lingkungan terbatas dengan dependensi yang sudah ditinjau.

Jika berhasil, ini membuktikan instalasi terkunci pada jalur yang diuji, bukan bahwa aplikasi pasti berfungsi. Paket yang memerlukan build script mungkin belum siap digunakan. Tinjau script terlebih dahulu, lalu jalankan pengujian aplikasi secara terisolasi sesuai kebijakan. Jangan menjalankan ulang seluruh script dengan hak administrator.

Yang tidak boleh menjadi solusi

  • Jangan menonaktifkan strict-ssl atau memakai NODE_TLS_REJECT_UNAUTHORIZED=0.
  • Jangan beralih ke registry HTTP atau mengaktifkan renegosiasi TLS yang tidak aman.
  • Jangan memasang legacy provider di profil shell sebagai “fix permanen”.
  • Jangan menghapus lockfile, membersihkan cache global secara paksa, atau menonaktifkan antivirus tanpa bukti dan persetujuan.

Kriteria selesai: penyebab didukung log/reproduksi, verifikasi sertifikat tetap aktif, endpoint dan runtime didukung, ping berhasil, lalu instalasi terkunci dan tes aplikasi pada salinan terisolasi lulus. Bila hanya ping yang berhasil, laporkan sebatas itu.

Referensi