1. 从一次批量补字段任务说起：MongoCursorNotFoundException 到底在报什么

如果你正在用 Java 驱动跑一个「给历史数据补字段」的批处理任务，跑着跑着突然抛出com.mongodb.MongoCursorNotFoundException: Query failed with error code -5，那你来对地方了。这个报错的核心含义其实很直白：你手里那个游标 ID，在 MongoDB 服务端已经不存在了。服务端不是「拒绝」你，而是「根本不认识」这个游标了。

先把这个错误拆开看。MongoCursorNotFoundException是 Java 驱动在收到服务端返回的错误码后翻译出来的异常类型，而error code -5就是 MongoDB 服务端定义的CursorNotFound。异常信息里通常会带一句Cursor 5741457193246430646 not found on server 106.75.51.20:35724，这串数字就是游标 ID。它出现的位置也很关键——堆栈里是QueryBatchCursor.getMore，说明问题发生在「客户端向服务端要下一批数据」这个动作上，而不是第一次查询。

那游标为什么会「消失」？这就要理解 MongoDB 的游标机制。find()返回的并不是全部结果，而是一个游标句柄。服务端默认行为是：第一次查询返回 101 个文档或 1MB（谁先到算谁），之后每次getMore再拉 4MB。同时，游标默认有 10 分钟空闲超时——如果这 10 分钟内客户端没有对这个游标发起任何操作，服务端就会把它回收掉，释放内存。

问题就出在这里。很多批处理任务的写法是「边遍历边写库」，比如遍历userop_record集合，对每条文档执行一次updateMany。如果单条更新慢、网络往返多、或者数据量大，一个批次（batch）的处理时间很容易超过 10 分钟。等你处理完这一批、再回头用同一个游标 ID 去getMore时，服务端早就把它清理了，于是error code -5就来了。

这个场景特别容易出现在「补时间戳字段」「数据迁移」「批量打标签」这类任务里。代码逻辑本身没错，错的是游标生命周期和业务处理耗时之间的失衡。理解这一点，后面的修复才有方向：要么让游标别那么快过期，要么让每批数据在超时前被消费完。前者有风险，后者才是工程上更稳的做法。

2. 修复前的准备：用 TaoToken 快速搭一个可复现的调试环境

排查这类问题，最怕的是「改一版、跑半天、看结果」。你需要一个能快速验证配置、随时切换模型来辅助读日志和生成代码的环境。我平时会用 TaoToken 来做这件事——它把主流大模型的调用统一成一个入口，省去到处找 Key、对参数的麻烦。

TaoToken 是什么？简单说，它是一个大模型 API 聚合平台，你拿到一个 Key，就能通过统一的 Base URL 调用不同厂商的模型。对做后端排障的人来说，它的价值在于：你可以把报错堆栈、MongoDB 日志片段直接丢给模型，让它帮你定位是哪一层的问题，而不用在多个平台之间来回切换。适合谁？适合需要频繁调试、写脚本、读日志的开发和运维同学。

接入方式很直接。Base URL 用https://taotoken.net/api，Key 在控制台的 API Keys 页面生成。如果你只是想先验证模型能不能正常对话，可以直接打开模型对话页面试一句；如果要长期跑编码或 Agent 任务，Coding Plan 会更划算。下面这张表把几个关键入口列清楚，方便你按需取用。

拿到 Key 之后，你可以先用一个最小的请求确认链路通不通。比如用 curl 发一条消息，看返回是否正常。这一步不是为了排查 MongoDB，而是确保你后面让模型帮忙分析日志时，调用是稳定的。环境搭好，再回到游标问题本身，效率会高很多。

3. 可复制的连接串与游标配置骨架：batchSize 与超时参数怎么设

修复的核心思路是：控制每个批次的大小，让客户端在 10 分钟内必须联系服务端至少一次。这样游标就不会因为空闲而被回收。具体到 Java 驱动，最直接的参数就是batchSize。

先看连接串。MongoDB 的连接串支持在 URI 里直接带参数，这样比在代码里零散设置更清晰、也更容易复制。下面是一个带关键参数的骨架：

mongodb://gg_user_db_rw:密码@106.75.51.20:35724/gg_user_db?authSource=gg_user_db&maxPoolSize=20&serverSelectionTimeoutMS=5000&socketTimeoutMS=60000

这里几个参数值得说明。authSource指定认证库，很多Authentication failed其实是认证库写错了。maxPoolSize控制连接池上限，批处理任务并发不高的话 20 足够。serverSelectionTimeoutMS是选节点超时，socketTimeoutMS是单次 socket 读写超时——注意，这个 socket 超时和游标超时是两回事，别混淆。

真正解决error code -5的是查询层面的batchSize。在 Java 驱动里这样写：

useropRecord.find(match) .batchSize(10000) .noCursorTimeout(false) .forEach(new Block<Document>() { @Override public void apply(Document doc) { Document update = new Document("$set", new Document("_tm", new BSONTimestamp((int)(System.currentTimeMillis() / 1000), 0))); useropRecord.updateMany(new BasicDBObject("_id", doc.get("_id")), update); } });

batchSize(10000)的含义是：每次getMore最多拉 10000 条。这样客户端处理完一批后，会主动去要下一批，间隔远小于 10 分钟，游标自然不会被回收。noCursorTimeout(false)是显式声明「不禁用超时」——我不建议用noCursorTimeout(true)，因为一旦任务异常退出，服务端游标会一直挂着占资源，得不偿失。

如果你用的是 Spring Data MongoDB，可以在application.yml里配置连接，再在查询时用Query对象设置 batchSize：

spring: data: mongodb: uri: mongodb://gg_user_db_rw:密码@106.75.51.20:35724/gg_user_db?authSource=gg_user_db

对应的查询代码：

Query query = new Query(Criteria.where("_tm").is(null) .and("date").gte(startDate) .and("code").is("S3_06")); query.cursorBatchSize(10000); mongoTemplate.find(query, Document.class, "userop_record") .forEach(doc -> { /* 更新逻辑 */ });

batchSize 到底设多少？这取决于你单条处理的耗时。原文作者实测「10 分钟大约更新 1 万条」，所以设 10000 刚好卡在超时边缘内。我的建议是：先测出你单条处理的平均耗时，再用 10 分钟除以它，取一个安全系数 0.5 到 0.7 的值。比如单条 30ms，10 分钟能处理 20000 条，那 batchSize 设 10000 到 14000 比较稳。设 5 万、3 万都报错，就是因为超过了实际处理能力。

4. 验证修复：从复现报错到确认游标不再失效

改完配置不能只看「没报错」，要有一套可验证的动作。第一步是复现。在修复前，用原来的代码跑一次，确认能稳定触发MongoCursorNotFoundException。复现时把日志级别调高，Java 驱动会打印getMore的细节。你可以在logback.xml里加：

<logger name="org.mongodb.driver" level="DEBUG"/>

这样能看到每次getMore的游标 ID 和返回条数。报错时，日志里会先出现一批getMore成功，然后某一次突然失败，失败前的那次成功到失败之间的时间间隔，往往就接近 10 分钟——这就是游标超时的直接证据。

第二步是验证修复。用batchSize(10000)重新跑，观察日志里getMore的调用频率。正常情况下，每隔几十秒到几分钟就会有一次getMore，间隔稳定，不会出现长时间静默。同时用 MongoDB 的命令行确认游标状态：

db.currentOp({ "command.getMore": { $exists: true } })

这个命令能看到当前活跃的getMore操作。如果任务运行中能看到游标在持续被拉取，说明生命周期是健康的。

第三步是结果校验。任务跑完后，统计被更新的文档数，和预期数量对比。比如：

db.userop_record.count({ "_tm": { $ne: null }, "code": "S3_06" })

如果这个数字和你的目标集合大小一致，说明没有因为游标中断而漏处理。我试过用这套方法跑一个下午加一个上午，没有再出现error code -5，而且更新条数和预期完全对得上。

这里有个细节要注意：updateMany在循环里逐条执行，本身效率不高。如果数据量特别大，可以考虑用bulkWrite批量提交，减少网络往返。但批量提交会改变单批处理耗时，所以 batchSize 要重新估算。原则不变：让每批处理时间稳稳落在游标超时之内。

5. 常见报错对照排查：401、local proxy failed、reading choices 与 OAuth

排障时最怕把不同层的错误混在一起。下面这张对照表把几个高频报错和它们的真实原因列清楚，方便你快速定位。

重点说401和local proxy failed。这两个在接入大模型 API 时特别常见。401九成是 Key 的问题——要么复制时带了空格，要么用了错误的认证头格式。正确写法是：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer 你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

local proxy failed则通常是本地网络环境导致的，检查一下系统网络设置，确认能正常访问外网即可。至于reading choices，多半是接口返回了错误信息而不是正常的choices数组，这时候别急着改代码，先把原始响应打印出来看。

如果你在用 Claude Code 或类似的编码工具，配置时要写全三件套：Base URL、Key、Model ID。缺一个都会导致请求失败。Base URL 用https://taotoken.net/api，Key 从控制台取，Model ID 按文档里列出的填。这三者对齐了，大部分接入问题都能避免。

6. 把游标问题一次讲透：从参数到习惯的收尾建议

回到最初那个补时间戳的任务。问题的本质不是代码写错了，而是没有考虑游标的生命周期。MongoDB 的游标超时机制是为了保护服务端资源，它不会因为你的任务「还没跑完」就网开一面。所以工程上的正确姿势是：主动控制消费节奏，让客户端的行为去适配服务端的规则。

具体到实践，我建议养成几个习惯。第一，任何遍历大集合的批处理，都显式设置batchSize，不要依赖默认值。第二，在循环里加一个计数器，每处理 N 条打印一次进度和耗时，这样你能直观看到单批处理时间，及时调整。第三，不要用noCursorTimeout(true)来「解决」问题，那只是把资源泄漏的风险往后推。第四，如果任务可能跑很久，考虑用「按时间分片」的方式，每次只处理一个时间窗口的数据，从根上避免长游标。

最后再强调一下验证的重要性。改完参数后，别只看「没报错」，要确认数据完整、游标行为正常。用db.currentOp看活跃游标，用count核对结果，用日志看getMore频率。这套动作做下来，你不仅修好了当前的问题，也建立了一套可复用的排查方法。下次再遇到error code -5，你会知道该看哪里、该改什么。