pymongo批量查询报InvalidBSON: year 0 is out of range错误如何解决

该报错的根本原因是BSON解码阶段，解析器尝试将一段二进制内容转换为Python datetime类型时，提取到的年份值为0，超出了Python datetime最小支持的年份1。你已确认文档本身无异常日期字段，可按以下优先级排查：

1. 排查bson模块冲突问题 #

90%以上的同类非文档本身问题的InvalidBSON报错，都是因为环境中同时安装了第三方bson包和pymongo自带的bson模块，二者解码逻辑不兼容：

• 执行以下命令重新安装正确依赖：

pip uninstall -y bson pymongo
pip install pymongo --upgrade

2. 调整游标拉取配置 #

错误仅在批量拉取特定批次触发，大概率和批次数据量过大导致的传输异常、解码缓冲区溢出有关：

• 调低游标批次大小，避免单次拉取数据量过大：

# 单次拉取返回的文档数从默认1000调整为200，可根据实际情况再降低
docs = col.find({}, batch_size=200)

• 关闭游标超时，避免长时遍历触发游标失效返回异常截断数据：

docs = col.find({}, no_cursor_timeout=True)
# 遍历完成后务必手动关闭游标释放资源
docs.close()

3. 显式配置BSON解码规则 #

关闭自动日期解码，规避解析逻辑异常：

• 初始化集合时传入自定义CodecOptions，关闭日期自动解析：

from bson.codec_options import CodecOptions, DatetimeConversion

# 配置日期解码规则，遇到异常日期直接返回原始时间戳而非抛出错误
codec_options = CodecOptions(
    datetime_conversion=DatetimeConversion.DATETIME_AUTO,
    tz_aware=False
)
# 或者完全禁止自动转换datetime，拿到原始BSON值后自行处理
codec_options = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_RAISE)

col = db.get_collection("your_collection_name", codec_options=codec_options)

4. 排查资源与网络问题 #

• 批量拉取时监控宿主机内存、TCP丢包情况，内存不足导致的缓冲区截断会让非日期字段的二进制内容被误识别为日期字段，抛出年份异常。
• 如果是从分片/副本集拉取数据，强制指定主库读取，避免从节点同步延迟返回结构异常的数据：

from pymongo import ReadPreference
col = db.get_collection("your_collection_name", read_preference=ReadPreference.PRIMARY)

5. 定位异常文档 #

如果以上方案均无效，可按_id分段拉取数据，缩小范围定位到触发异常的具体文档，手动导出该文档的原始BSON进行解码，排查是否存在未校验到的嵌套数组/嵌套对象内的隐藏无效日期字段。

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