Keycloak Setup Errors & Resolutions

✅ Correct Startup Command for Keycloak 26.x

Use only the --proxy-headers flag, and enable HTTP since NGINX handles TLS:

bash
nohup ./kc.sh start \ 
--http-enabled=true \ 
--http-host=192.168.0.25 \ 
--proxy-headers=xforwarded \ 
--hostname-strict=false \ 
> output.log 2>&1 &

Explanation:

• --proxy-headers=xforwarded: Tells Keycloak to trust the X-Forwarded-* headers from NGINX

• --http-enabled=true: Required when TLS is terminated by a proxy

• --hostname-strict=false: Allows Keycloak to accept the hostname provided by the proxy

❌ Do not use --proxy=edge—Keycloak 26 now uses the proxy-headers system exclusively

1. Unable to Kill Keycloak Started with nohup

🔍 Problem

You tried:

bash
kill $(cat keycloak.pid) 
kill -9 $(cat keycloak.pid)

But received:

arduino
No such process

Even repeated nohup ./kc.sh start ... led to unexpected behavior and exit code 2.

🛠 Root Causes

• The PID file may not match the actual Java process running Keycloak, only the wrapper script kc.sh.

• nohup detaches the process; after wrapper exits, the real process continues under a new PID.

✅ Solution

bash
# 1. Find the Java process 
ps -ef | grep '[q]uarkus.bootstrap.runner.QuarkusEntryPoint' 
# 2. Kill it gracefully 
kill <PID> 
# 3. If that fails, force kill 
kill -9 <PID> 
# 4. Confirm termination 
pgrep -f 'QuarkusEntryPoint' || echo "Stopped" 
# 5. Clean up stale files 
rm -f keycloak.pid output.log nohup.out

Tip: When starting Keycloak, capture the actual Java PID:

bash
nohup ./kc.sh start … & sleep 3 
pgrep -f 'QuarkusEntryPoint' > keycloak.pid

This ensures you're always targeting the correct process.

2. ❌ NGINX Reverse Proxy Missing Critical Headers

🔍 Problem

Your existing NGINX config lacks headers needed by Keycloak:

nginx
proxy_set_header X-Real-IP …; 
proxy_set_header X-Forwarded-For …; 
proxy_set_header X-Forwarded-Proto …;

Missing headers can cause:

• Mixed‑content (HTTP assets on HTTPS page)

• "Invalid redirect_uri" errors

• Blank or broken admin console

✅ Corrected NGINX SSL Block

nginx
{
  proxy_pass http://192.168.0.25:8080; 
  proxy_set_header Host $host; 
  proxy_set_header X-Forwarded-Host $host; 
  proxy_set_header X-Forwarded-Port $server_port; 
  proxy_set_header X-Forwarded-Proto $scheme; 
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 }

Why this is needed:

• X-Forwarded-Proto & others ensure Keycloak sees the true https:// URL and correct host/port, fixing asset loading and redirect issues.

• Client IP logging/auditing requires X-Real-IP and X-Forwarded-For.