apache/seatunnel · error · MongodbConnectorException

ILLEGAL_ARGUMENT

ILLEGAL_ARGUMENT

Error message

Poll change stream records failed

What it means

Wrapper thrown by MongodbStreamFetchTask.execute when polling the MongoDB change stream cursor raises any exception. The original cause is swallowed (not chained) in this message, so the underlying MongoDB error must be found in preceding logs.

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:230

                    // Reach the high watermark, the binlog fetcher should be finished
                    if (currentOffset.isAtOrAfter(streamSplit.getStopOffset())) {
                        // send watermark end event
                        SourceRecord watermark =
                                WatermarkEvent.create(
                                        createWatermarkPartitionMap(descriptor.toString()),
                                        "__mongodb_watermarks",
                                        streamSplit.splitId(),
                                        WatermarkKind.END,
                                        currentOffset);

                        queue.enqueue(new DataChangeEvent(watermark));
                        break;
                    }
                }
            }
        } catch (Exception e) {
            throw new MongodbConnectorException(
                    ILLEGAL_ARGUMENT, "Poll change stream records failed");
        } finally {
            taskRunning = false;
            if (changeStreamCursor != null) {
                changeStreamCursor.close();
            }
        }
    }

    @Override
    public boolean isRunning() {
        return taskRunning;
    }

    @Override
    public void shutdown() {
        taskRunning = false;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check worker logs immediately before this error for the underlying MongoDB driver exception
2. Verify network stability and connection-string failover settings (replicaSet, multiple hosts)
3. Reduce time the stream is idle or ensure the oplog window covers the pause (oplog size)
4. From a checkpoint restart, the stream task will reopen with the last resume token; if the token expired, restart from a new snapshot

Example fix

// before: small oplog window loses resume tokens
// after (mongod.conf): increase oplog size
replication:
  oplogSizeMB: 20480

// pre-check: ensure replica set reachable and oplog window healthy
MongoDatabase admin = client.getDatabase("admin");
Document st = admin.runCommand(new Document("replSetGetStatus", 1));

try { pollRecords() } catch (MongodbConnectorException e) { if ("Poll change stream records failed".equals(e.getMessage())) { backoffAndReopenCursor(); } else { throw e; } }

When it happens

Trigger: Any failure while iterating the change-stream cursor: connection drop, cursor timeout/idle, replica-set election invalidating the cursor, resume-token no longer valid, or deserialization errors.

Common situations: MongoDB replica set elections during deployments; network partitions; change stream left idle beyond server's cursor lifetime; oplog rolling over so the resume token expires.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• ILLEGAL_ARGUMENT
• UNSUPPORTED_OPERATION
• 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/7e1719da1aea4aff. Report an issue: GitHub.