Keycloak Realm Not Found: Causes and Solutions

Last updated: March 2026

The “Realm does not exist” or “Realm not found” error in Keycloak is deceptively simple. Something is trying to access a realm endpoint, but Keycloak does not recognize the realm name in the URL. The fix is usually straightforward once you identify the root cause, but the number of possible causes can make debugging frustrating.

This guide covers every common reason for realm not found errors, with diagnostic commands and solutions for each.

Quick Diagnosis

Before diving into specific causes, run these diagnostic commands to narrow down the problem:

# List all realms in Keycloak
# First, get an admin token
TOKEN=$(curl -s -X POST 
  http://localhost:8080/realms/master/protocol/openid-connect/token 
  -d "client_id=admin-cli" 
  -d "username=admin" 
  -d "password=admin" 
  -d "grant_type=password" | jq -r '.access_token')

# List realms
curl -s http://localhost:8080/admin/realms 
  -H "Authorization: Bearer ${TOKEN}" | jq '.[].realm'

If the admin token request itself fails with “realm not found,” the master realm is inaccessible, which points to a more fundamental startup issue (see Cause 5 below).

# Using the Keycloak Admin CLI (kcadm.sh)
/opt/keycloak/bin/kcadm.sh config credentials 
  --server http://localhost:8080 
  --realm master 
  --user admin 
  --password admin

/opt/keycloak/bin/kcadm.sh get realms --fields realm

Cause 1: Typo in the Realm Name

The most common cause. Realm names in URLs are case-sensitive and must match exactly.

Diagnosis

Compare the realm name in your request with the actual realm name in Keycloak:

# What your application is requesting
echo "Requested: my-realm"

# What Keycloak has
curl -s http://localhost:8080/admin/realms 
  -H "Authorization: Bearer ${TOKEN}" | jq '.[].realm'

Common Mistakes

• My-Realm vs my-realm (case mismatch)
• my_realm vs my-realm (underscore vs hyphen)
• myrealm vs my-realm (missing separator)
• Trailing spaces or invisible characters in configuration files

Fix

Update your application configuration to use the exact realm name:

# Test that the exact realm name works
curl -s http://localhost:8080/realms/my-realm/.well-known/openid-configuration | jq '.issuer'

If the OIDC discovery document returns successfully, the realm name is correct. Use our JWT Token Analyzer to check the iss claim in tokens you receive – the issuer URL contains the exact realm name.

Cause 2: Wrong URL Pattern (Keycloak Version Issue)

Keycloak 17+ (Quarkus-based) changed the default URL pattern by removing the /auth/ prefix. This is the single most common cause of realm not found errors after a Keycloak upgrade.

URL Pattern Changes

Endpoint	Keycloak 16 and earlier (WildFly)	Keycloak 17+ (Quarkus)
Realm endpoint	/auth/realms/{realm}	/realms/{realm}
Token endpoint	/auth/realms/{realm}/protocol/openid-connect/token	/realms/{realm}/protocol/openid-connect/token
Admin console	/auth/admin/	/admin/
Admin REST API	/auth/admin/realms/{realm}	/admin/realms/{realm}
OIDC discovery	/auth/realms/{realm}/.well-known/openid-configuration	/realms/{realm}/.well-known/openid-configuration
JWKS	/auth/realms/{realm}/protocol/openid-connect/certs	/realms/{realm}/protocol/openid-connect/certs
User info	/auth/realms/{realm}/protocol/openid-connect/userinfo	/realms/{realm}/protocol/openid-connect/userinfo

Diagnosis

Try both URL patterns:

# New pattern (Keycloak 17+)
curl -sf http://localhost:8080/realms/my-realm/.well-known/openid-configuration 
  && echo "New pattern works"

# Old pattern (Keycloak 16 and earlier)
curl -sf http://localhost:8080/auth/realms/my-realm/.well-known/openid-configuration 
  && echo "Old pattern works"

Fix Option 1: Update Your Application

Update all realm URLs in your application configuration to use the new pattern without /auth/:

# Before (Keycloak 16)
KEYCLOAK_ISSUER=http://keycloak:8080/auth/realms/my-realm

# After (Keycloak 17+)
KEYCLOAK_ISSUER=http://keycloak:8080/realms/my-realm

For Next.js with NextAuth:

// Before
issuer: "http://keycloak:8080/auth/realms/my-realm",

// After
issuer: "http://keycloak:8080/realms/my-realm",

For Spring Boot:

# Before
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://keycloak:8080/auth/realms/my-realm

# After
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://keycloak:8080/realms/my-realm

Fix Option 2: Restore the /auth/ Prefix

If you cannot update all clients immediately, configure Keycloak to use the old URL pattern:

# In keycloak.conf
http-relative-path=/auth

# Or via environment variable
KC_HTTP_RELATIVE_PATH=/auth

# Or in Docker
docker run -e KC_HTTP_RELATIVE_PATH=/auth quay.io/keycloak/keycloak:26.1.0 start-dev

This is a temporary measure. Plan to migrate all clients to the new URL pattern.

For a comprehensive upgrade guide, see our post on Keycloak 26 migration steps and upgrading from Keycloak 8 to 24.

Cause 3: Realm Was Not Imported

If you are using realm imports (via JSON files or environment variables), the import might have failed silently.

Diagnosis

Check the Keycloak startup logs for import messages:

docker logs keycloak 2>&1 | grep -i "import|realm"

Look for messages like:

# Success
Realm 'my-realm' imported

# Failure
ERROR: Could not import realm from file
WARN: Realm import file not found

Common Import Failures

File not found:

# Wrong
volumes:
  - ./realm.json:/opt/keycloak/data/import/realm.json

# Check if the file actually exists at the mount point
docker exec keycloak ls -la /opt/keycloak/data/import/

Missing --import-realm flag:

# This will NOT import realms
command: start-dev

# This WILL import realms
command: start-dev --import-realm

Invalid JSON:

# Validate your realm JSON
cat realm.json | jq empty
# If no output, JSON is valid. If errors, fix the JSON.

Import runs only once:

Keycloak’s --import-realm flag only imports on the first startup. If the database already has a master realm, subsequent imports of new realms might be skipped depending on the import strategy.

Fix

For Docker Compose, ensure the import is configured correctly:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.1.0
    command: start-dev --import-realm
    volumes:
      - ./realm-export.json:/opt/keycloak/data/import/realm-export.json:ro
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin

If the realm should have been imported but was not, import it manually:

# Import via Admin REST API
curl -X POST http://localhost:8080/admin/realms 
  -H "Authorization: Bearer ${TOKEN}" 
  -H "Content-Type: application/json" 
  -d @realm-export.json

Or use the Admin CLI:

/opt/keycloak/bin/kcadm.sh create realms -f /path/to/realm-export.json

For automated realm management across environments, see our guide on Keycloak CI/CD with GitHub Actions.

Cause 4: Realm Was Deleted or Disabled

Realms can be disabled (making them inaccessible) or deleted entirely.

Diagnosis

Check if the realm exists but is disabled:

curl -s http://localhost:8080/admin/realms 
  -H "Authorization: Bearer ${TOKEN}" 
  | jq '.[] | {realm: .realm, enabled: .enabled}'

Fix

Re-enable a disabled realm:

curl -X PUT "http://localhost:8080/admin/realms/my-realm" 
  -H "Authorization: Bearer ${TOKEN}" 
  -H "Content-Type: application/json" 
  -d '{"enabled": true}'

If the realm was deleted, you will need to recreate it from a backup or realm export. With Skycloak, automated backups make recovery straightforward.

Cause 5: Keycloak Failed to Start Properly

If the master realm itself is not found, Keycloak likely did not complete its initialization.

Diagnosis

# Check if Keycloak is actually running
docker ps | grep keycloak

# Check for startup errors
docker logs keycloak 2>&1 | grep -i "error|exception|failed" | head -20

# Check the health endpoint
curl -sf http://localhost:9000/health/ready

Common Startup Failures

Database issues:

# Keycloak cannot create its schema
ERROR: Failed to initialize database
# Fix: Check database connectivity and permissions

Port conflicts:

# Another process is using port 8080
ERROR: Address already in use
# Fix: Stop the conflicting process or change Keycloak's port

See our Keycloak connection refused troubleshooting guide for detailed diagnostics.

Cause 6: Proxy or Load Balancer URL Rewriting

If Keycloak sits behind a reverse proxy, the proxy might be stripping or modifying the URL path, causing the realm name to be lost.

Diagnosis

# Test directly against Keycloak (bypassing the proxy)
curl -sf http://keycloak-internal:8080/realms/my-realm/.well-known/openid-configuration

# Test through the proxy
curl -sf https://auth.example.com/realms/my-realm/.well-known/openid-configuration

If the direct connection works but the proxy connection does not, the proxy configuration is the problem.

Common Proxy Issues

Nginx stripping the path:

# Wrong - forwards to root, losing /realms/my-realm
location / {
    proxy_pass http://keycloak:8080;
}

# Correct - preserves the path
location / {
    proxy_pass http://keycloak:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
}

Double path prefix:

If your proxy adds a prefix and Keycloak has a relative path configured, you might get double prefixes:

# Proxy forwards /auth/* to Keycloak
# Keycloak has KC_HTTP_RELATIVE_PATH=/auth
# Result: Keycloak sees /auth/auth/realms/my-realm -> not found

Make sure the proxy path and Keycloak’s KC_HTTP_RELATIVE_PATH are coordinated. See our guide on running Keycloak behind a reverse proxy for detailed configuration.

Cause 7: Multi-Tenancy URL Confusion

If your application uses Keycloak’s multi-tenancy features (multiple realms), make sure you are sending requests to the correct realm.

Diagnosis

When using identity brokering or the Organizations feature, the URL structure can be confusing:

# The authentication realm (where users log in)
/realms/main-realm/protocol/openid-connect/token

# An identity provider realm (where users are redirected for SSO)
/realms/partner-realm/protocol/openid-connect/auth

# These are different realms and both must exist

For multi-tenancy patterns, see our guide on multi-tenancy with Keycloak Organizations.

Cause 8: OIDC Discovery URL Mismatch

Some OIDC client libraries cache the discovery document. If the realm URL changes (version upgrade, hostname change), the cached configuration points to the wrong realm.

Diagnosis

Check what your OIDC library is using for the issuer:

# Get the current OIDC configuration
curl -s http://localhost:8080/realms/my-realm/.well-known/openid-configuration | jq '.issuer'

# Compare with what your application has configured
# The issuer in the token MUST match the issuer in the discovery document

Use our JWT Token Analyzer to decode a token and check the iss claim. It must match the issuer URL in the OIDC discovery document exactly, including protocol (http vs https) and port.

Fix

Clear your application’s OIDC discovery cache and ensure the configured issuer matches Keycloak’s actual issuer URL:

# The issuer URL format for Keycloak 17+
http://keycloak:8080/realms/my-realm

# NOT
http://keycloak:8080/auth/realms/my-realm  # Old format
http://keycloak:8080/realms/my-realm/       # Trailing slash
https://keycloak:8080/realms/my-realm       # Wrong protocol

Cause 9: Kubernetes Ingress Path Routing

In Kubernetes deployments, ingress controllers sometimes modify the request path before it reaches Keycloak.

Diagnosis

# Check ingress configuration
kubectl get ingress -o yaml | grep -A 10 "paths:"

# Test from inside the cluster
kubectl run curl-test --image=curlimages/curl --rm -it -- 
  curl -v http://keycloak-service:8080/realms/my-realm

Common Issues

Path-based routing stripping the prefix:

# Wrong - strips /keycloak prefix, Keycloak receives /realms/my-realm
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
    - host: auth.example.com
      http:
        paths:
          - path: /keycloak(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: keycloak
                port:
                  number: 8080

If your ingress rewrites the path, make sure KC_HTTP_RELATIVE_PATH matches the expected path structure. For detailed Kubernetes deployment guidance, see our guide on deploying Keycloak with ArgoCD.

Cause 10: Environment Variable Interpolation Errors

When configuring Keycloak URLs through environment variables, interpolation errors can silently produce wrong realm names.

Diagnosis

# Check what your application actually sees
docker exec my-app env | grep KEYCLOAK

# Common issues:
# KEYCLOAK_ISSUER=http://keycloak:8080/realms/$REALM  # $REALM not expanded
# KEYCLOAK_ISSUER=http://keycloak:8080/realms/         # Empty realm name
# KEYCLOAK_ISSUER="http://keycloak:8080/realms/my-realm " # Trailing whitespace

Fix

In Docker Compose, ensure proper variable substitution:

environment:
  # Use the literal realm name when possible
  KEYCLOAK_ISSUER: http://keycloak:8080/realms/my-realm

  # If using variable substitution, verify the variable is set
  # KEYCLOAK_ISSUER: http://keycloak:8080/realms/${REALM_NAME}

In Kubernetes, use configMapKeyRef or explicit values rather than string interpolation in the pod spec.

Prevention

To avoid realm not found errors in the first place:

1. Use OIDC discovery instead of hardcoding endpoints. Configure the issuer URL and let your OIDC library fetch all other URLs from the discovery document.

2. Automate realm configuration with GitOps. Store realm exports in version control and apply them automatically. See our GitHub Actions CI/CD guide.

3. Use integration tests with Testcontainers to catch URL mismatches before deployment.

4. Monitor realm accessibility by checking the OIDC discovery endpoint in your monitoring system. If it returns a non-200 status, alert immediately.

5. Use managed Keycloak with Skycloak to eliminate infrastructure-level issues. Skycloak handles upgrades, hostname configuration, and health monitoring, reducing the surface area for realm-related errors.

Further Reading

• Keycloak Server Administration Guide
• Keycloak Connection Refused Troubleshooting
• Keycloak 403 Forbidden Troubleshooting
• Keycloak Invalid Grant Error Troubleshooting
• Keycloak SSL Certificate Error Fix
• Keycloak Token Expired Troubleshooting

---

Realm configuration errors are one of the most common Keycloak issues, but they disappear when someone else manages your Keycloak infrastructure. Skycloak provides managed Keycloak with guaranteed SLA and expert support. See pricing to get started.