{"record":{"id":"5fb5b0ed52a3437f","repo":"apache/seatunnel","slug":"unsupported-operation-5fb5b0","errorCode":"UNSUPPORTED_OPERATION","errorMessage":"Illegal $changeStream operation: %s %s","messagePattern":"Illegal \\$changeStream operation: (.+?) (.+?)","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/MongodbStreamFetchTask.java","lineNumber":316,"sourceCode":"\n        try {\n            return (MongoChangeStreamCursor<BsonDocument>)\n                    changeStreamIterable.withDocumentClass(BsonDocument.class).cursor();\n        } catch (MongoCommandException e) {\n            if (e.getErrorCode() == FAILED_TO_PARSE_ERROR\n                    || e.getErrorCode() == UNKNOWN_FIELD_ERROR) {\n                if (e.getErrorMessage().contains(\"startAtOperationTime\")) {\n                    supportsStartAtOperationTime = false;\n                    return openChangeStreamCursor(changeStreamDescriptor);\n                } else if (e.getErrorMessage().contains(\"startAfter\")) {\n                    supportsStartAfter = false;\n                    return openChangeStreamCursor(changeStreamDescriptor);\n                } else {\n                    throw new MongodbConnectorException(\n                            ILLEGAL_ARGUMENT, \"Open change stream failed\");\n                }\n            } else if (e.getErrorCode() == ILLEGAL_OPERATION_ERROR) {\n                throw new MongodbConnectorException(\n                        UNSUPPORTED_OPERATION,\n                        String.format(\n                                \"Illegal $changeStream operation: %s %s\",\n                                e.getErrorMessage(), e.getErrorCode()));\n\n            } else if (e.getErrorCode() == UNAUTHORIZED_ERROR) {\n                throw new MongodbConnectorException(\n                        UNSUPPORTED_OPERATION,\n                        String.format(\n                                \"Unauthorized $changeStream operation: %s %s\",\n                                e.getErrorMessage(), e.getErrorCode()));\n\n            } else if (!forceTimestampStartup && MongodbUtils.checkIfResumeTokenExpires(e)) {\n                log.info(\"Failed to open cursor with resume token, fallback to timestamp startup\");\n                return openChangeStreamCursor(changeStreamDescriptor, true);\n            } else {\n                throw new MongodbConnectorException(ILLEGAL_ARGUMENT, \"Open change stream failed\");\n            }","sourceCodeStart":298,"sourceCodeEnd":334,"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/MongodbStreamFetchTask.java#L298-L334","documentation":"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.","triggerScenarios":"openChangeStreamCursor receives a MongoCommandException with getErrorCode() == ILLEGAL_OPERATION while starting the change stream — typically unsupported options on this deployment type.","commonSituations":"Opening a change stream on a standalone mongod; requesting options (like startAfter or a specific pipeline) unsupported by the server version; mongos routing restrictions.","solutions":["Run MongoDB as a replica set (replSet) or sharded cluster — change streams are illegal on standalone nodes","Check the error message/code in the exception for which option is illegal","Remove or adjust change-stream options unsupported by your MongoDB version","Upgrade MongoDB if the server version predates the required change-stream feature"],"exampleFix":"// before: standalone node\nmongod --dbpath /data/db\n// after: replica set\nmongod --dbpath /data/db --replSet rs0 && mongosh --eval 'rs.initiate()'","handlingStrategy":"validation","validationCode":"Document isMaster = client.getDatabase(\"admin\").runCommand(new Document(\"isMaster\", 1));\nif (isMaster.getString(\"msg\") != null && isMaster.getString(\"msg\").equals(\"isdbgrid\")) { /* mongos ok */ }\nelse if (!isMaster.containsKey(\"setName\")) throw new IllegalStateException(\"$changeStream illegal on standalone\");","typeGuard":null,"tryCatchPattern":"try { openCursor() } catch (MongodbConnectorException e) { if (e.getErrorCodeName() != null && e.getMessage().contains(\"Illegal $changeStream\")) { removeUnsupportedOptions(); retry(); } else { throw e; } }","preventionTips":["Run against a replica set or sharded cluster","Avoid change-stream options unsupported by your server version","Test the $changeStream aggregation manually with the same credentials"],"tags":["mongodb","cdc","change-stream","illegal-operation"],"backgroundTag":"unsupported-operation","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"}