How to Fix Keycloak Theme Error

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

Keycloak returns Theme "custom-theme" not found or the login page shows a white screen with no styles — the custom theme directory is missing or the theme.properties file is incorrectly configured.

The Problem

WARN [org.keycloak.theme] (default task-1) Theme "mytheme" not found, falling back to default

Step-by-Step Fix

Step 1: Create theme directory structure

sudo mkdir -p /opt/keycloak/themes/mytheme/login
sudo mkdir -p /opt/keycloak/themes/mytheme/account
sudo mkdir -p /opt/keycloak/themes/mytheme/email
sudo mkdir -p /opt/keycloak/themes/mytheme/admin

Step 2: Create theme.properties

# /opt/keycloak/themes/mytheme/theme.properties
parent=base
import=common/keycloak

Step 3: Create a custom login template

<!-- /opt/keycloak/themes/mytheme/login/login.ftl -->
<#import "template.ftl" as layout>
<@layout.registrationLayout displayInfo=true; section>
    <#if section = "form">
        <form id="kc-login-form" action="${url.loginAction}" method="post">
            <div class="form-group">
                <label for="username">${msg("username")}</label>
                <input id="username" name="username" type="text" class="form-control" />
            </div>
            <div class="form-group">
                <label for="password">${msg("password")}</label>
                <input id="password" name="password" type="password" class="form-control" />
            </div>
            <button type="submit" class="btn btn-primary">${msg("doLogIn")}</button>
        </form>
    </#if>
</@layout.registrationLayout>

Step 4: Configure Keycloak to use the theme

# /opt/keycloak/conf/keycloak.conf
spi-theme-static-max-age=2592000
spi-theme-cache-themes=true
spi-theme-cache-templates=true
spi-theme-default=mytheme

Step 5: Restart Keycloak

sudo /opt/keycloak/bin/kc.sh restart

Step 6: Verify theme is loaded

Check the server log for Loaded theme mytheme

Prevention Tips

• Always inherit from a base theme (parent=base)
• Keep themes in the global themes directory
• Test theme changes with a dedicated test realm
• Use the Keycloak Theme Manager for version control

Common Mistakes with theme error

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

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