apache/seatunnel · error · MongodbConnectorException

UNSUPPORTED_OPERATION

UNSUPPORTED_OPERATION

Error message

Illegal $changeStream operation: %s %s

What it means

Thrown when MongoDB rejects the $changeStream command with ILLEGAL_OPERATION error code (e.g. 20 IllegalOperation), meaning the requested change-stream operation is not legal on the target server/deployment.

Source

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

        try {
            return (MongoChangeStreamCursor<BsonDocument>)
                    changeStreamIterable.withDocumentClass(BsonDocument.class).cursor();
        } catch (MongoCommandException e) {
            if (e.getErrorCode() == FAILED_TO_PARSE_ERROR
                    || e.getErrorCode() == UNKNOWN_FIELD_ERROR) {
                if (e.getErrorMessage().contains("startAtOperationTime")) {
                    supportsStartAtOperationTime = false;
                    return openChangeStreamCursor(changeStreamDescriptor);
                } else if (e.getErrorMessage().contains("startAfter")) {
                    supportsStartAfter = false;
                    return openChangeStreamCursor(changeStreamDescriptor);
                } else {
                    throw new MongodbConnectorException(
                            ILLEGAL_ARGUMENT, "Open change stream failed");
                }
            } else if (e.getErrorCode() == ILLEGAL_OPERATION_ERROR) {
                throw new MongodbConnectorException(
                        UNSUPPORTED_OPERATION,
                        String.format(
                                "Illegal $changeStream operation: %s %s",
                                e.getErrorMessage(), e.getErrorCode()));

            } else if (e.getErrorCode() == UNAUTHORIZED_ERROR) {
                throw new MongodbConnectorException(
                        UNSUPPORTED_OPERATION,
                        String.format(
                                "Unauthorized $changeStream operation: %s %s",
                                e.getErrorMessage(), e.getErrorCode()));

            } else if (!forceTimestampStartup && MongodbUtils.checkIfResumeTokenExpires(e)) {
                log.info("Failed to open cursor with resume token, fallback to timestamp startup");
                return openChangeStreamCursor(changeStreamDescriptor, true);
            } else {
                throw new MongodbConnectorException(ILLEGAL_ARGUMENT, "Open change stream failed");
            }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Run MongoDB as a replica set (replSet) or sharded cluster — change streams are illegal on standalone nodes
2. Check the error message/code in the exception for which option is illegal
3. Remove or adjust change-stream options unsupported by your MongoDB version
4. Upgrade MongoDB if the server version predates the required change-stream feature

Example fix

// before: standalone node
mongod --dbpath /data/db
// after: replica set
mongod --dbpath /data/db --replSet rs0 && mongosh --eval 'rs.initiate()'

Document isMaster = client.getDatabase("admin").runCommand(new Document("isMaster", 1));
if (isMaster.getString("msg") != null && isMaster.getString("msg").equals("isdbgrid")) { /* mongos ok */ }
else if (!isMaster.containsKey("setName")) throw new IllegalStateException("$changeStream illegal on standalone");

try { openCursor() } catch (MongodbConnectorException e) { if (e.getErrorCodeName() != null && e.getMessage().contains("Illegal $changeStream")) { removeUnsupportedOptions(); retry(); } else { throw e; } }

When it happens

Trigger: openChangeStreamCursor receives a MongoCommandException with getErrorCode() == ILLEGAL_OPERATION while starting the change stream — typically unsupported options on this deployment type.

Common situations: Opening a change stream on a standalone mongod; requesting options (like startAfter or a specific pipeline) unsupported by the server version; mongos routing restrictions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• ILLEGAL_ARGUMENT
• ILLEGAL_ARGUMENT
• Non-heartbeat record has no documentKey field, this is unexp
• 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/5fb5b0ed52a3437f. Report an issue: GitHub.