msal4j报AcquireTokenByClientCredentialSupplier失败如何排查

抛出的核心异常是ClassCastException: java.util.Collections$SingletonList cannot be cast to java.lang.String，触发点在Nimbus OAuth2 SDK序列化HTTP请求参数的环节，本质是参数类型不匹配，常见触发场景有三类：

• 构建客户端凭证请求参数时，权限范围（scopes）传值格式错误，出现了嵌套集合：比如把一个List整体作为元素塞进了另一个List，导致参数Map里存在List嵌套List的结构，序列化时预期取字符串值，实际拿到的是SingletonList类型的集合实例，强转失败。
• 项目存在依赖冲突：手动引入了和当前msal4j版本不兼容的低版本oauth2-oidc-sdk包（堆栈里显示的是5.64.4版本），版本不匹配导致SDK内部参数处理逻辑和msal4j的传参逻辑不兼容，触发类型转换错误。
• 自定义扩展参数传值类型错误：如果通过extraHttpParameters给请求加了自定义参数，参数Map的value传入了集合、自定义对象等非字符串类型值，也会触发这个强转异常。

• 修正scopes传参格式：客户端凭证模式的scopes必须是每个权限字符串作为List/Set的独立元素，禁止嵌套集合，正确写法示例：

// 正确传参示例，不要嵌套集合
Set<String> scopes = Collections.singleton("https://graph.microsoft.com/.default");
ClientCredentialParameters parameters = ClientCredentialParameters.builder(scopes).build();

同时检查clientId、clientSecret、authority、tenant等基础配置参数，确认这些字段都传入字符串类型值，没有误传集合类型。

• 排查修复依赖冲突：通过Maven/Gradle的依赖树查看命令检查oauth2-oidc-sdk的实际引入版本，不要手动单独声明这个依赖的低版本，直接使用msal4j传递引入的对应版本即可；如果有其他第三方组件传递引入了低版本nimbus SDK，通过依赖排除规则去掉低版本，保留msal4j要求的兼容版本。
• 检查自定义扩展参数：如果配置了额外HTTP参数，确认所有参数的value都是字符串类型，不要传入集合、实体对象等非字符串值。

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