Certificate pinning failure! SSL / TLS Origin: Network OSI layer 6 · Presentation Last updated 4 Nov 2026

Android/OkHttp: javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure! Peer certificate chain: sha256/... Pinned certificates for api.example.com

The app's pinned certificate/public-key hash does not match the one the server presented, so OkHttp blocked the request.

Exact message you may see Certificate pinning failure!javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!Peer certificate chain: sha256/ Pinned certificates forCertificate pinning failure Peer certificate chainCertificatePinner failure
Explore the map of this error Full error map →
Seen on: SSL Android

Meaning

Pinning ties the app to specific keys. After a certificate renewal with a new key (or a CDN/proxy change) the old pin fails. Pin to the intermediate or use backup pins, rotate pins before expiry via an app update, and never test through intercepting proxies with pinning enabled.

Common causes

  • Certificate rotated with a new key
  • CDN/proxy changed the presented chain
  • Intercepting proxy (Charles/mitmproxy) while pinned
  • Wrong hash or host in CertificatePinner
  • No backup pin configured

⚡ Quick fix

  1. Update the pin set to include current and next keys
  2. Pin intermediate CA public keys for resilience
  3. Print the actual chain hashes from the exception and compare

Detailed fix by platform

Android

  1. The exception lists sha256/... for each presented cert; copy the right one into CertificatePinner.Builder().add("api.example.com", "sha256/...")

How to diagnose

  1. Pins — Match presented hashes?
  2. Rotation — Key changed?
  3. Proxy — Intercepting?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Network. Errors that are often confused with or caused by this one (click to open):

AH01909: server certificate does NOT include an ID which matches the server name — Apache: [ssl:warn] AH01909: example.com:443:0 server certificate does NOT include an ID which matches the server name (SSL / TLS)AH01909: server certi…CAA record forbids issuance — Let's Encrypt/CA: CAA record for example.com prevents issuance (SSL / TLS)CAA record forbids is…gRPC: Ssl handshake failed / authentication handshake failed — gRPC: rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: x509: certificate signed by unknown authority" (SSL / TLS)gRPC: Ssl handshake f…HandshakeException: CERTIFICATE_VERIFY_FAILED — Dart: HandshakeException: Handshake error in client (OS Error: CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate) (Flutter / Dart)HandshakeException: C…NSURLErrorServerCertificateUntrusted (-1202) — iOS: Error Domain=NSURLErrorDomain Code=-1202 "The certificate for this server is invalid. You might be connecting to a server that is pretending to be 'example.com'" (SSL / TLS)NSURLErrorServerCerti…SSLCertificateFile: file does not exist — Apache: AH02240: Server should be SSL-aware but has no certificate configured / SSLCertificateFile: file '/etc/ssl/x.crt' does not exist or is empty (SSL / TLS)SSLCertificateFile: f…Timeout during connect (likely firewall problem) — Let's Encrypt: Fetching http://example.com/.well-known/acme-challenge/token: Timeout during connect (likely firewall problem) (SSL / TLS)Timeout during connec…Certifica…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.