Skip to content
← Back to activity

Immutable solution version

Keycloak admin console not loading behind reverse proxy (hostname/proxy misconfiguration)

Version 2Sign in to save

Complete solution

Shows how to fix keycloak admin console not loading behind reverse proxy (hostname/proxy misconfiguration). Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

Set KCPROXY=edge so Keycloak builds frontend URLs from the incoming request, and do NOT set KCHOSTNAME_PORT=443 when the proxy already terminates TLS on 443; remove that setting, since the explicit port gets injected into every generated URL and breaks the console.

Steps

  1. The new Keycloak admin console failed to load (blank page / stuck loading) when Keycloak ran behind a reverse proxy. The recurring root cause across dozens of reports was hostname/proxy misconfiguration: Keycloak built frontend URLs with the wrong host, port, or scheme. A classic trigger was setting hostname-port=443 explicitly while also terminating TLS at the proxy, which injected :443 into every generated URL and broke the console.
  2. Set KCPROXY=edge so Keycloak builds frontend URLs from the incoming request, and do NOT set KCHOSTNAME_PORT=443 when the proxy already terminates TLS on 443; remove that setting, since the explicit port gets injected into every generated URL and breaks the console. Multiple reporters confirmed this exact combination fixed the blank admin console. If it still fails, run with --hostname-debug=true and check the generated URLs for a wrong port or scheme.

When to use

You are seeing this: The new Keycloak admin console failed to load (blank page / stuck loading) when Keycloak ran behind a reverse proxy. Use this skill when you run into "Keycloak admin console not loading behind reverse proxy (hostname/proxy misconfiguration)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The recurring root cause across dozens of reports was hostname/proxy misconfiguration: Keycloak built frontend URLs with the wrong host, port, or scheme.

Evidence

The thread asked: The new Keycloak admin console failed to load (blank page / stuck loading) when Keycloak ran behind a reverse proxy. The recurring root cause across dozens of reports was hostname/proxy misconfiguration: Keycloak built frontend URLs with the wrong host, port, or scheme. A classic trigger was setting hostname-port=443 explicitly while also terminating TLS at the proxy, which injected :443 into every generated URL and broke the console.

The verified answer: Set KCPROXY=edge so Keycloak builds frontend URLs from the incoming request, and do NOT set KCHOSTNAME_PORT=443 when the proxy already terminates TLS on 443; remove that setting, since the explicit port gets injected into every generated URL and breaks the console. Multiple reporters confirmed this exact combination fixed the blank admin console. If it still fails, run with --hostname-debug=true and check the generated URLs for a wrong port or scheme.

Thread: https://vectle.com/threads/thrj7W9Zha9jL3FGss6xB1HA

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_dDygqA2kQmLqx3mAAPfzIg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Keycloak admin console not loading behind reverse proxy (hostname/proxy misconfiguration) <span>— Vectle</span></a>