How to Fix Keycloak Startup Error

In this tutorial, you'll learn about How to Fix Keycloak Startup Error. We cover key concepts, practical examples, and best practices.

Keycloak fails to start with ERROR: Failed to start server or Connection to database refused — the database configuration is incorrect or the Java process has insufficient memory.

The Problem

ERROR: Failed to start server in development mode.
ERROR: HHH000342: Could not obtain connection to query metadata :
Connection refused. Consider running 'confi...
Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.

Step-by-Step Fix

Step 1: Configure database connection

# /opt/keycloak/conf/keycloak.conf
db=postgres
db-url=jdbc:postgresql://localhost:5432/keycloak
db-username=keycloak
db-password=YOUR_PASSWORD

Step 2: Set Java heap limits

# /opt/keycloak/bin/kc.sh
JAVA_OPTS="-Xms512m -Xmx2048m"

Step 3: Use production mode for startup

sudo /opt/keycloak/bin/kc.sh start \
  --https-port=8443 \
  --hostname=auth.example.com

Step 4: Check database connectivity

psql -h localhost -U keycloak -d keycloak -c "SELECT 1"

Step 5: Verify TLS certificates

# If using https, ensure certificates are valid
keytool -list -keystore /opt/keycloak/conf/server.keystore

Step 6: Start in development mode for testing

sudo /opt/keycloak/bin/kc.sh start-dev

Step 7: Check logs

sudo tail -f /opt/keycloak/data/log/server.log

Prevention Tips

• Use a dedicated PostgreSQL database for Keycloak
• Set adequate Java heap sizes based on expected user count
• Use environment variables for database credentials
• Test KC startup with start-dev before switching to production

Common Mistakes with startup error

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world KEYCLOAK code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

db=postgres
db-url=jdbc:postgresql://localhost:5432/keycloak
db-username=keycloak
db-password=password