databricks-connect运行报错Invalid shard address如何排查解决

问题表现 #

运行databricks-connect提交代码时抛出如下错误，此前配置正常无改动，同团队多人同时触发相同报错：

22/06/24 13:24:48 ERROR SparkClientManager: Fail to get the SparkClient
java.util.concurrent.ExecutionException: com.databricks.service.SparkServiceConnectionException: Invalid shard address

触发原因 #

该批量突发的报错基本不是本地配置写错导致，核心原因是Databricks服务端调整了工作区的分片路由规则，本地databricks-connect缓存的旧分片地址失效，客户端未自动刷新缓存就会抛出该异常。

修复步骤 #

• 重置本地databricks-connect配置缓存，执行命令：
  databricks-connect configure --reset
  该操作会清空本地存储的工作区地址、访问令牌、集群ID等配置，执行前提前备份好相关参数。
• 重新执行配置流程，运行命令：
  databricks-connect configure
  按提示依次填入工作区HTTPS地址、个人访问令牌、目标集群ID、集群端口（默认15001）、组织ID即可。
• 配置完成后先做连通性校验，执行：
  databricks-connect test
  等所有检查项全部通过后，再运行业务代码。
• 若重配后仍报错，先核对本地databricks-connect版本和远端集群的Databricks Runtime（DBR）版本是否完全匹配：版本不匹配（哪怕是小版本差一号）也会导致分片地址解析失败，比如集群用DBR 12.2 LTS，本地必须安装对应12.2.x版本的databricks-connect，禁止跨版本使用。
• 紧急场景临时恢复方案：在任务运行前注入环境变量DATABRICKS_API_BASE_URL，值设为当前工作区的完整HTTPS地址，可强制客户端跳过本地缓存的分片地址，直接走指定服务入口路由。

注意：不要手动修改本地用户目录下.databricks-connect配置文件硬编码shard地址，后续服务端路由调整时会再次触发同类报错，通过官方配置命令重配是长期有效方案。

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