修改目录列表模式下Databricks Auto Loader路径时遇错误

问题场景 #

• 使用Databricks DBR 14.3 LTS结合Auto Loader执行每日数据摄入任务，加载Azure Data Lake Storage Gen2中按日期组织的目录数据
• 根据Databricks文档，DBR 11.3 LTS及以上版本中，修改目录列表模式的Auto Loader输入路径无需更换检查点目录，但修改路径后触发如下错误：

Failed to initialize filesystem abfss://abc@def.dfs.core.windows.net/input/20240227: Failure to initialize configuration for storage account def.dfs.core.windows.net: Invalid configuration value detected for fs.azure.account.keyInvalid configuration value detected for fs.azure.account.key

• 执行代码如下：

(
    spark
    .readStream
    .format("cloudFiles")
    .option("cloudFiles.format", "avro")
    .option("cloudFiles.schemaLocation", SCHEMA_LOCATION_DIR)
    .option("cloudFiles.schemaEvolutionMode", "rescue")
    .load("abfss://abc@def.dfs.core.windows.net/input/20240228")
    .select("_metadata", "*")
    .writeStream
    .format("delta")
    .option("checkpointLocation", CHECKPOINT_LOCATION_DIR)
    .option("mergeSchema", "true")
    .outputMode("append")
    .trigger(availableNow=True)
    .toTable("catalog.schema.table")
)

• 注：abfss://abc@def.dfs.core.windows.net已在Unity Catalog中配置为外部位置

错误原因 #

• 检查点元数据残留冲突：检查点目录中留存了旧路径（如报错中的20240227目录）的存储认证配置，该配置中的fs.azure.account.key存在无效值（为空、格式错误或已过期）。Auto Loader启动时会复用检查点中的元数据，包括旧路径的存储配置，这会覆盖Unity Catalog外部位置的认证设置，导致新路径初始化时读取到无效密钥。
• 认证方式不统一：如果之前的任务曾手动设置过fs.azure.account.key这类底层存储配置，而当前依赖Unity Catalog外部位置的权限管理，两者的认证逻辑冲突，检查点中留存的旧配置会干扰新任务的权限验证。

解决建议 #

• 临时修复：清空检查点目录中的元数据，或临时更换检查点目录运行一次任务，验证新路径可正常加载后，再考虑是否换回原检查点（需确认进度是否需要保留）。
• 长期规范：统一使用Unity Catalog外部位置管理存储权限，避免在代码中手动设置fs.azure.account.key等底层存储配置，确保任务依赖统一的认证体系。
• 前置验证：先通过Spark批处理方式读取新路径的文件，确认Unity Catalog外部位置的权限配置正常，排除路径本身的访问问题。

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