Keycloak 502 Bad Gateway behind a reverse proxy
· 8 min read
A Keycloak 502 Bad Gateway never comes from Keycloak. RFC 9110 defines 502 as a status a gateway emits about its upstream — so the proxy is telling you it could not get a usable response out of Keycloak, and the explanation is in the proxy's error log rather than anywhere in Keycloak's configuration. Start there, every time. In nginx there are only six lines that produce a 502 in front of Keycloak, each maps to one cause, and three of the six are the Quarkus-era port layout catching out a config written for an older release.
Everything below was reproduced against Keycloak 26.8.1 behind nginx 1.29, and every error string is copied out of a real run.