apache/seatunnel · error · MongodbConnectorException

ILLEGAL_ARGUMENT

ILLEGAL_ARGUMENT

Error message

Record has no documentKey field but is not a heartbeat event. This indicates an unexpected record type: ${record}

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mongodb/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mongodb/source/fetch/MongodbFetchTaskContext.java:181

    public boolean isDataChangeRecord(SourceRecord record) {
        return MongodbRecordUtils.isDataChangeRecord(record);
    }

    @Override
    public boolean isRecordBetween(
            SourceRecord record, @Nonnull Object[] splitStart, @Nonnull Object[] splitEnd) {
        BsonDocument documentKey = getDocumentKey(record);
        if (documentKey == null) {
            if (isHeartbeatEvent(record)) {
                log.debug(
                        "Heartbeat record has no documentKey field, skipping range check. Record: {}",
                        record);
                return false;
            }
            log.warn(
                    "Non-heartbeat record has no documentKey field, this is unexpected. Record: {}",
                    record);
            throw new MongodbConnectorException(
                    ILLEGAL_ARGUMENT,
                    "Record has no documentKey field but is not a heartbeat event. "
                            + "This indicates an unexpected record type: "
                            + record);
        }
        BsonDocument splitKeys = (BsonDocument) splitStart[0];
        String firstKey = splitKeys.getFirstKey();
        BsonValue keyValue = documentKey.get(firstKey);
        BsonValue lowerBound = ((BsonDocument) splitStart[1]).get(firstKey);
        BsonValue upperBound = ((BsonDocument) splitEnd[1]).get(firstKey);

        if (isFullRange(lowerBound, upperBound)) {
            return true;
        }

        return isValueInRange(lowerBound, keyValue, upperBound);
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the change stream is watching only collections whose event types are supported (insert/update/replace/delete), not an entire cluster with command events
2. Upgrade the SeaTunnel MongoDB CDC connector to a version that classifies the new MongoDB event type
3. Inspect the offending record logged in the exception to identify which event type leaked in
4. If using a custom offset/resume token, reset the streaming split to a valid change-stream position

Example fix

// before: watch whole database, receiving unsupported events
MongoDBIncrementalSource.builder().database("db").build();
// after: restrict to specific collections with supported events
MongoDBIncrementalSource.builder().database("db").collection("users").build();

BsonDocument record = ...;
boolean isHeartbeat = !record.containsKey("documentKey") && record.getString("operationType", null) == null;
boolean isProcessable = record.containsKey("documentKey") || isHeartbeat;
if (!isProcessable) throw new IllegalStateException("Unexpected change-stream record: " + record);

boolean hasDocumentKey(BsonDocument r) { return r != null && r.containsKey("documentKey"); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Non-heartbeat record has no documentKey field, this is unexp
• ILLEGAL_ARGUMENT
• UNSUPPORTED_OPERATION
• Change stream cursor has expired, trying to recreate cursor
• Resume token has expired, fallback to timestamp restart mode

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/6d6b6d98873f150f. Report an issue: GitHub.