Databricks执行writeStream时报checkpoint路径下SST文件不存在错误

数据老陈

2026-10-3

问题场景

在Databricks环境中执行如下结构化流写入函数时任务运行失败：

def _write_stream(data_frame, checkpoint_path, write_stream_path):
        data_frame.writeStream.format("delta") \
            .option("checkpointLocation", checkpoint_path) \
            .trigger(processingTime="1 second") \
            .option("mergeSchema", "true") \
            .outputMode("append") \
            .table(write_stream_path)

抛出java.io.FileNotFoundException: No such file or directory错误，异常核心原因如下：

Caused by: java.io.FileNotFoundException: No such file or directory:
s3:///checkpoint/sources/0/rocksdb/SSTs/.sst
错误指向S3检查点路径下的RocksDB SST状态存储文件不存在。

排查步骤

验证S3路径权限：确认Databricks集群关联的IAM角色/访问密钥对报错的S3检查点路径有s3:ListBucket、s3:GetObject权限，权限不足也会抛出FileNotFoundException误报。
检查文件完整性：直接访问报错的S3路径，确认对应.sst文件是否真的不存在，同时检查检查点路径是否存在拼写错误。
排查文件清理操作：确认是否存在S3生命周期规则、手动清理脚本误删了检查点目录下的文件，RocksDB的SST文件是流任务状态持久化的核心文件，删除后会直接导致任务重启失败。
检查S3一致性：如果S3 Bucket开启了跨区域复制或版本控制，确认文件同步完成，同步延迟会导致临时找不到文件的问题。

解决方案

快速恢复方案（可接受状态丢失场景）：如果业务允许流任务重新消费源数据，直接删除整个检查点目录后重启任务即可，任务会重新初始化状态，按配置的起始位置重新消费数据。
状态保留方案：如果不想丢失已有的消费状态，可将Databricks Runtime升级到11.3 LTS及以上版本，高版本针对RocksDB SST文件丢失场景做了容错逻辑，部分场景下可自动恢复损坏的状态。
永久规避方案：
- 禁止手动修改、删除检查点目录下的任何文件，配置S3生命周期规则时排除检查点目录
- 给流任务增加状态优化配置，避免RocksDB文件无限膨胀：在writeStream参数中增加.option("rocksdb.compaction.enabled", "true")开启自动压缩，同时配置.option("maxFilesPerTrigger", "1000")控制单次处理文件量
- 如果频繁出现S3一致性问题，可开启S3强一致性特性，或调整检查点存储路径到IO延迟更低的存储介质。

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