Spring Boot集成Keycloak部署独立Tomcat报not a subtype错误如何解决

排查方向 #

这个错误本质是Keycloak相关类的加载冲突，独立Tomcat和Spring Boot内置Tomcat的类加载机制、依赖环境不同，按以下顺序排查即可：

• 版本对齐校验
  先检查独立Tomcat的lib目录下是否已经部署了全局的Keycloak Tomcat适配器jar包，如果存在，确认其版本与你的Spring Boot应用中引入的Keycloak依赖版本完全一致。如果版本不同，要么统一Tomcat全局适配器版本，要么在你的项目pom/gradle配置中将所有Keycloak相关依赖的scope设为provided，直接使用Tomcat全局提供的包，避免两个不同版本的类被不同类加载器加载，触发子类型校验失败。
• 依赖重复排查
  用依赖分析命令（Maven执行mvn dependency:tree，Gradle执行gradle dependencies）检查项目中是否引入了多个版本的Keycloak相关包（重点排查keycloak-adapter-core、keycloak-policy-enforcer），统一所有Keycloak依赖的版本号后重新打war包。也可以直接解压war包，查看WEB-INF/lib目录下是否存在多个版本的Keycloak jar包，删除冗余的旧版本包验证。
• 类加载顺序调整
  独立Tomcat默认采用父类加载器优先的加载逻辑，若不想修改Tomcat全局配置，可以在应用的src/main/webapp/META-INF目录下新增context.xml文件，添加配置<Loader delegate="false"/>，强制应用优先加载自身WEB-INF/lib下的依赖包，避开父类加载器中不匹配的Keycloak类的影响。
• 冗余配置清理
  你已将Keycloak配置放在application.properties中，检查项目资源目录和war包中是否同时存在多余的keycloak.json配置文件，两个配置源同时存在会在独立Tomcat环境下触发重复初始化逻辑，删除冗余的json配置文件即可。
• 非必要功能关闭
  若你的业务不需要用到Keycloak的细粒度权限策略管控，直接删除keycloak.json中的"policy-enforcer": {}配置，或在application.properties中添加keycloak.policy-enforcer.enable=false，直接关闭Policy Enforcer加载逻辑，从根源上避开这个初始化错误。

内容的提问来源于stack exchange，提问作者bluen