Keycloak stuck on a loading screen usually stems from database connectivity failures, browser cache corruption, or misconfigured proxy headers. Resolving this requires verifying the underlying service health, clearing client-side caches, and ensuring the application server can communicate with its data store without network interruptions.
Verify Database Connectivity
The most common cause for Keycloak hanging indefinitely during startup is an inability to establish a connection with the configured database. If the application cannot read its schema or write session data, it will fail silently while displaying the initial load spinner. You must confirm that the database host is reachable and accepting connections on the expected port. Check the logs of your database container or instance to ensure it is running and not rejecting connections due to authentication errors. For PostgreSQL, verify that the user has the correct permissions and that the firewall rules allow traffic from the Keycloak host. If you are using Docker, ensure the database service is listed in the same network as the Keycloak container. A successful connection test often involves pinging the database host from within the Keycloak environment or using a database client tool to connect manually. If the connection times out, check your network configuration, DNS resolution, and any intermediate firewalls that might be blocking the specific port used by your database engine. Troubleshooting Java Connect Exception: Connection Refused in Docker Compose Spring Boot Keycloak provides detailed steps for resolving similar network-level issues when Keycloak runs in a containerized environment.Clear Browser Cache and Cookies
Sometimes the issue is not with the server but with the client browser retaining outdated or corrupted resources. Modern web applications like Keycloak rely heavily on JavaScript bundles and CSS files. If a previous update changed these files significantly, the browser may attempt to load a mismatched version, causing the initialization script to hang. Start by performing a hard refresh of the page. In most browsers, this is achieved by pressing Ctrl+F5 on Windows or Cmd+Shift+R on macOS. This forces the browser to ignore cached versions and download fresh assets from the server. If the problem persists, proceed to clear the entire cache for the Keycloak domain. Navigate to your browser settings and locate the privacy or history section. Select the option to clear browsing data, ensuring that only cached images and files are selected if you wish to preserve other login sessions. Alternatively, try accessing the Keycloak login page using an incognito or private window. If the page loads correctly in private mode, the issue is definitively related to your local browser cache or extensions. Disable any ad blockers or security extensions temporarily, as these can sometimes interfere with the AJAX calls made during the Keycloak initialization process. These extensions may block specific endpoints required for the authentication flow, leading to a perpetual loading state.Check Proxy and Header Configuration
When Keycloak is deployed behind a reverse proxy such as Nginx, Apache, or HAProxy, incorrect header forwarding can break the application's ability to determine its own base URL. The application needs accurate information about the scheme (HTTP vs HTTPS) and the host name to generate correct links and tokens. Ensure that your proxy is configured to pass the X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port headers to the Keycloak backend. Without these headers, Keycloak might assume it is running on HTTP when it is actually served over HTTPS, causing mixed content warnings or redirect loops that manifest as a loading screen. Review your proxy configuration file and add the necessary proxy_set_header directives if they are missing. For example, in Nginx, you would typically include lines that map the incoming request headers to the backend variables. Restarting the proxy service after making these changes is essential to apply the new configuration. Additionally, verify that the Keycloak realm settings match the public-facing URL. If the realm is configured for localhost but accessed via a domain name, the browser will reject cookies or scripts due to origin mismatches. Adjust the valid URIs in the realm settings to include both the internal and external addresses.Inspect Server Logs for Errors
If the above steps do not resolve the issue, the root cause lies deeper within the application logic or environment. The server logs contain critical information about failed deployments, missing modules, or runtime exceptions that prevent the UI from rendering. Locate the log file for your Keycloak installation. If you are using Docker, use the docker logs command followed by the container ID to view real-time output. Look for stack traces or error messages that appear just before the application stops responding. Common indicators include "Failed to start" messages or database driver errors. Enable debug logging temporarily to gain more visibility into the startup sequence. While this generates verbose output, it can help pinpoint exactly which component fails during initialization. Once identified, revert the logging level to reduce performance overhead. Pay attention to memory-related errors. If the JVM runs out of heap space during startup, the application may crash silently or enter a degraded state where the frontend cannot fetch necessary data. Ensure that the allocated memory limits are sufficient for your deployment size.Frequently Asked Questions
Why does Keycloak load slowly after fixing the database?
Initial database migrations or index rebuilding can take significant time depending on the data volume. Wait for the migration process to complete fully before attempting to access the admin console again.
Can SSL certificate errors cause a loading screen?
Yes, invalid or expired SSL certificates can break the WebSocket connections used for real-time updates. Ensure all certificates are valid and properly chained to avoid silent connection failures.
How do I reset the Keycloak admin password if I am locked out?
You can reset the password directly from the database by hashing a new value and updating the credential record. Use the built-in hash utility provided by Keycloak to generate the correct format.
Is it safe to delete the browser cache every time this happens?
Clearing the cache is generally safe and recommended as a first troubleshooting step. It resolves issues caused by stale JavaScript bundles without affecting server-side data or configurations.
What should I do if the database is healthy but Keycloak still hangs?
Check the network latency between the Keycloak server and the database. High latency or packet loss can cause timeouts during the initialization phase, leading to a frozen interface.