Keycloak邮件主题设置报错：无法找到text/email-test.ftl模板

测试SMTP连接时出现EmailException: Failed to template email，且提示找不到text/email-test.ftl系列模板，即使手动创建文件仍报错，可按以下步骤排查解决：

• 确认模板路径正确性
  Keycloak的邮件模板必须放在对应Realm使用主题的指定目录下，路径结构为：

  • 本地部署：{Keycloak安装目录}/themes/{当前主题}/email/text/
  • Docker部署：容器内路径为/opt/keycloak/themes/{当前主题}/email/text/
    替换{当前主题}为你Realm实际使用的主题（默认主题为keycloak），若使用自定义主题，需对应到自定义主题的目录。

• 检查文件权限
  确保Keycloak进程拥有模板文件的读取权限：

  • Linux/macOS本地部署：执行命令修改权限

    chmod 644 /path/to/themes/{当前主题}/email/text/*.ftl
    chmod 755 /path/to/themes/{当前主题}/email/text/
    

  • Docker部署：确认挂载的主题目录权限符合容器内keycloak用户的访问要求，可通过docker exec -it {容器名} chown -R keycloak:keycloak /opt/keycloak/themes/{当前主题}调整。

• 验证模板内容格式
  模板需为有效的FreeMarker格式，避免语法错误。可使用基础测试模板内容：
  email-test.ftl示例：

  <#assign subject="Test Email">
  This is a test email sent from Keycloak.
  

  同时确保文件编码为UTF-8，避免读取异常。

• 重启Keycloak服务
  手动添加模板后，Keycloak的模板缓存不会自动刷新，需重启服务加载新模板：

  • 本地部署：执行{Keycloak安装目录}/bin/kc.sh stop后再启动kc.sh start（Windows系统用kc.bat）
  • Docker部署：执行docker restart {容器名称}

• 确认Realm主题配置
  进入Realm Settings → Themes页面，检查Email项的主题设置是否与你放置模板的主题一致，若设置为其他主题，需将模板迁移至对应主题目录。

内容的提问来源于stack exchange，提问作者John Téllez