---
id: 31
type: blog
title: "Why Cloudflare Returned SSL Handshake Failed 525"
slug: "why-cloudflare-ssl-handshake-failed-525"
canonical_url: "https://docs.phatysd.me/content/why-cloudflare-ssl-handshake-failed-525"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "Web Blog > Engineering Journal > Networking"
topics:
  - "Cloudflare"
  - "TLS"
  - "Heroku"
  - "Incident analysis"
tags:
  - "cloudflare"
  - "ssl"
  - "tls"
  - "heroku"
  - "debugging"
related:
  - slug: "deployment-runbook-heroku-cloudflare"
    title: "Deployment Runbook: Heroku + Cloudflare"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"
---

# Why Cloudflare Returned SSL Handshake Failed 525

A browser can show a secure Cloudflare certificate while Cloudflare still fails to create a secure connection to the origin. That is the key to understanding Error 525.

## What 525 means

Cloudflare documents Error 525 as a failed SSL handshake between Cloudflare and the origin. It occurs with `Full` or `Full (Strict)` mode when the origin-side negotiation fails. Typical causes include no valid origin certificate, an unavailable secure port, SNI issues, or incompatible cipher suites.

The error is not automatically evidence that the visitor-to-Cloudflare connection is broken.

## The useful mental model

```text
Browser ── HTTPS ──> Cloudflare ── HTTPS ──> Heroku origin
```

There are two TLS connections. Debug them separately. The browser lock only describes the first leg.

## The investigation

The first useful commands were:

```bash
curl -Iv https://docs.phatysd.me/
heroku domains -a <APP>
heroku certs -a <APP>
heroku logs --tail -a <APP>
```

Then I compared the timestamp of the Cloudflare error with the origin logs. If Heroku sees no request, the failure is before the application: DNS, the custom-domain target, TLS, or Cloudflare's origin connection.

## DNS and encryption mode are connected

The Cloudflare DNS record must point to the exact origin target supplied by Heroku. The encryption mode must match the certificate and hostname served by that origin. `Flexible` can hide an origin that does not support HTTPS by using HTTP on the second leg, but it is not a good permanent design for a production app that should use HTTPS end to end.

Cloudflare recommends `Full` or `Full (Strict)` when the origin supports them. `Full (Strict)` adds origin certificate validation, so the certificate and hostname need to be correct.

## The durable fix

The durable fix is not repeatedly toggling Cloudflare modes. It is to make the origin serve valid HTTPS, keep the custom-domain target correct, use a compatible encryption mode, and verify the public hostname after propagation. The app's canonical URL and OAuth callback must use the same public origin.

## Takeaway

Treat 525 as a two-hop TLS incident. Check the edge and the origin independently, use timestamps, and avoid confusing a dyno port or a Cloudflare edge certificate with proof that the origin handshake works.

## References

- [Cloudflare Error 525](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-525/)
- [Cloudflare encryption modes](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/)
- [Configure Cloudflare and Heroku over HTTPS](https://developers.cloudflare.com/support/third-party-software/other/configure-cloudflare-and-heroku-over-https/)
