{"record":{"id":"6d6b6d98873f150f","repo":"apache/seatunnel","slug":"illegal-argument-6d6b6d","errorCode":"ILLEGAL_ARGUMENT","errorMessage":"Record has no documentKey field but is not a heartbeat event. This indicates an unexpected record type: ${record}","messagePattern":"Record has no documentKey field but is not a heartbeat event\\. This indicates an unexpected record type: (.+?)","errorType":"error_code","errorClass":"MongodbConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-mongodb/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mongodb/source/fetch/MongodbFetchTaskContext.java","lineNumber":181,"sourceCode":"    public boolean isDataChangeRecord(SourceRecord record) {\n        return MongodbRecordUtils.isDataChangeRecord(record);\n    }\n\n    @Override\n    public boolean isRecordBetween(\n            SourceRecord record, @Nonnull Object[] splitStart, @Nonnull Object[] splitEnd) {\n        BsonDocument documentKey = getDocumentKey(record);\n        if (documentKey == null) {\n            if (isHeartbeatEvent(record)) {\n                log.debug(\n                        \"Heartbeat record has no documentKey field, skipping range check. Record: {}\",\n                        record);\n                return false;\n            }\n            log.warn(\n                    \"Non-heartbeat record has no documentKey field, this is unexpected. Record: {}\",\n                    record);\n            throw new MongodbConnectorException(\n                    ILLEGAL_ARGUMENT,\n                    \"Record has no documentKey field but is not a heartbeat event. \"\n                            + \"This indicates an unexpected record type: \"\n                            + record);\n        }\n        BsonDocument splitKeys = (BsonDocument) splitStart[0];\n        String firstKey = splitKeys.getFirstKey();\n        BsonValue keyValue = documentKey.get(firstKey);\n        BsonValue lowerBound = ((BsonDocument) splitStart[1]).get(firstKey);\n        BsonValue upperBound = ((BsonDocument) splitEnd[1]).get(firstKey);\n\n        if (isFullRange(lowerBound, upperBound)) {\n            return true;\n        }\n\n        return isValueInRange(lowerBound, keyValue, upperBound);\n    }\n","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-mongodb/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mongodb/source/fetch/MongodbFetchTaskContext.java#L163-L199","documentation":"Thrown by MongodbFetchTaskContext.isRecordBetween when a change-stream record has neither a documentKey field nor a heartbeat ('operationType': null) designation. The connector only understands change events and heartbeat events, so an unrecognized record shape is treated as a broken invariant of the change stream.","triggerScenarios":"The incremental (stream) split receives a change-stream document lacking 'documentKey' whose operationType is not absent/null — e.g. MongoDB internal or command events leaking into the watched stream, or a non-change-stream document being injected into the record queue.","commonSituations":"Watching a collection/database where MongoDB emits unsupported events; custom resume-token or offset manipulation replaying malformed records; MongoDB version emitting new event types the connector doesn't classify; proxy/sharding layers rewriting change documents.","solutions":["Verify the change stream is watching only collections whose event types are supported (insert/update/replace/delete), not an entire cluster with command events","Upgrade the SeaTunnel MongoDB CDC connector to a version that classifies the new MongoDB event type","Inspect the offending record logged in the exception to identify which event type leaked in","If using a custom offset/resume token, reset the streaming split to a valid change-stream position"],"exampleFix":"// before: watch whole database, receiving unsupported events\nMongoDBIncrementalSource.builder().database(\"db\").build();\n// after: restrict to specific collections with supported events\nMongoDBIncrementalSource.builder().database(\"db\").collection(\"users\").build();","handlingStrategy":"validation","validationCode":"BsonDocument record = ...;\nboolean isHeartbeat = !record.containsKey(\"documentKey\") && record.getString(\"operationType\", null) == null;\nboolean isProcessable = record.containsKey(\"documentKey\") || isHeartbeat;\nif (!isProcessable) throw new IllegalStateException(\"Unexpected change-stream record: \" + record);","typeGuard":"boolean hasDocumentKey(BsonDocument r) { return r != null && r.containsKey(\"documentKey\"); }","tryCatchPattern":null,"preventionTips":["Watch specific collections, not the whole cluster, to avoid exotic event types","Keep the connector version in sync with the MongoDB server version","Log and inspect unexpected records before resuming from custom offsets"],"tags":["mongodb","cdc","change-stream","unexpected-record"],"backgroundTag":"internal-invariant-violation","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}