Keycloak主题login.ftl文件FreeMarker语法错误求助

错误核心原因 #

报错明确指出FreeMarker指令嵌套不匹配：在第100行第1列遇到</@layout.registrationLayout>标签，但当前上下文仅允许闭合#if指令，说明模板中存在#if未正确闭合、或者@layout.registrationLayout标签开闭不匹配的问题，即使回滚修改，也可能是缓存或主题加载异常导致旧模板未被替换。

排查与解决步骤 #

• 核对模板指令嵌套完整性
  找到login.ftl第100行附近的代码，重点检查：

  • 所有#if指令是否都有对应的</#if>闭合标签，且嵌套层级正确；
  • </@layout.registrationLayout>对应的<@layout.registrationLayout>开启标签是否存在，且未错误嵌套在#if块内部；
    建议直接对比Keycloak官方原始主题的login.ftl文件，逐行校验指令开闭逻辑。

• 强制清理Keycloak主题缓存
  回滚后问题未消失，大概率是缓存未失效：

  1. 停止Keycloak服务；
  2. 删除以下目录的全部内容（根据部署方式调整路径）：
     • 独立部署：standalone/data/tmp、standalone/data/theme-cache
     • 域部署：domain/data/tmp、domain/data/theme-cache
  3. 重启Keycloak，让服务重新加载主题文件。

• 检查主题继承配置
  若自定义主题继承自官方主题（如base或keycloak），确认：

  • theme.properties中的parent属性配置正确；
  • 父主题的模板文件未被意外修改。

• 校验模板语法细节
  检查所有FreeMarker指令的语法正确性：

  • 避免把</#if>误写为</if>；
  • 自定义标签的开闭标签名称完全一致（如@layout.registrationLayout的开闭标签需严格对应）。

用户提供的错误代码片段 #

<#if realm.password && social.providers??>
        <div id="kc-social-providers" class="${properties.kcFormSocialAccountSectionClass!}">
            <hr/>
            <h4>${msg("identity-provider-login-label")}</h4>
            <ul class="${properties.kcFormSocialAccountListClass!} <#if social.providers?size gt 3>${properties.kcFormSocialAccountListGridClass!}</#if>">
                <#list social.providers as p>
                    <a id="social-${p.alias}" class="${properties.kcFormSocialAccountListButtonClass!} <#if social.providers?size gt 3>${properties.kcFormSocialAccountGridItem!}</#if>" type="button" href="${p.loginUrl}">
                        <#if p.iconClasses?has_content>
                            <i class="${properties.kcCommonLogoIdP!} ${p.iconClasses!}" aria-hidden="true"></i>
                            <span class="${properties.kcFormSocialAccountNameClass!} kc-social-icon-text">${p.displayName!}</span>
                        <#else>
                            <span class="${properties.kcFormSocialAccountNameClass!}">${p.displayName!}</span>
                        </#if>
                    </a>
                </#list>
            </ul>
        </div>
    </#if>

完整错误栈 #

08:02:44,093 ERROR [org.keycloak.forms.login.freemarker.FreeMarkerLoginFormsProvider] (default task-1) Failed to process template: org.keycloak.theme.FreeMarkerException: Failed to process template login.ftl
    at org.keycloak.keycloak-services@16.1.1//org.keycloak.theme.FreeMarkerUtil.processTemplate(FreeMarkerUtil.java:71)
    ...
    at java.base/java.lang.Thread.run(Thread.java:829)

内容的提问来源于stack exchange，提问作者Thaer Abu Al Rub