apache/seatunnel · error · MongodbConnectorException

ILLEGAL_ARGUMENT

ILLEGAL_ARGUMENT

Error message

Execute snapshot read subtask for mongodb split %s fail

What it means

A catch-all wrapper thrown by MongodbScanFetchTask.execute when executing a snapshot (or stream backfill) subtask for a MongoDB split fails with any exception. It preserves the root cause while labeling the failure with the split being read.

Source

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

            final boolean streamBackfillRequired =
                    dataBackfillSplit.getStopOffset().isAfter(dataBackfillSplit.getStartupOffset());

            if (!streamBackfillRequired) {
                changeEventQueue.enqueue(
                        new DataChangeEvent(
                                WatermarkEvent.create(
                                        createWatermarkPartitionMap(collectionId.identifier()),
                                        "__mongodb_watermarks",
                                        dataBackfillSplit.splitId(),
                                        WatermarkKind.END,
                                        dataBackfillSplit.getStopOffset())));
            } else {
                MongodbStreamFetchTask dataBackfillTask =
                        new MongodbStreamFetchTask(dataBackfillSplit);
                dataBackfillTask.execute(taskContext);
            }
        } catch (Exception e) {
            throw new MongodbConnectorException(
                    ILLEGAL_ARGUMENT,
                    String.format(
                            "Execute snapshot read subtask for mongodb split %s fail",
                            snapshotSplit),
                    e);
        } finally {
            taskRunning = false;
        }
    }

    @Nonnull
    private MongoCursor<RawBsonDocument> getSnapshotCursor(
            @Nonnull SnapshotSplit snapshotSplit,
            MongodbSourceConfig sourceConfig,
            MongoClient mongoClient) {
        MongoCollection<RawBsonDocument> collection =
                getMongoCollection(mongoClient, snapshotSplit.getTableId(), RawBsonDocument.class);
        BsonDocument startKey = (BsonDocument) snapshotSplit.getSplitStart()[1];

View on GitHub (pinned to cf67b549a7)

Solutions

Read the 'Caused by' exception to find the actual root cause (auth, timeout, network, change-stream failure)
Verify network connectivity and replica set health between SeaTunnel workers and MongoDB
Increase MongoDB socket/connection timeouts if the snapshot is large
Re-run the job — snapshot splits are checkpointable and will resume from the failed split

Example fix

// before
MongoClientSettings.builder().applyToSocketSettings(b -> b.connectTimeout(10, SECONDS)).build();
// after
MongoClientSettings.builder().applyToSocketSettings(b -> b.connectTimeout(60, SECONDS).readTimeout(0, SECONDS)).build();

Defensive patterns

Strategy: retry

Validate before calling

// verify connectivity before submitting the job
try (MongoClient c = MongoClients.create(uri)) { c.getDatabase("admin").runCommand(new BsonDocument("ping", new BsonInt32(1))); }

Try / catch

try { runJob() } catch (MongodbConnectorException e) { /* 'Execute snapshot read subtask ... fail' — inspect cause, then resume job from checkpoint */ }

Prevention

Use a replica-set connection string with all hosts listed
Size snapshot parallelism and timeouts for the collection size
Monitor replica set health before and during snapshotting

When it happens

Trigger: Any exception inside snapshot split reading — MongoDB connection failure, query timeout, cursor exhaustion, authorization error, or failure executing the nested data-backfill stream task.

Common situations: MongoDB server restart or network partition mid-snapshot; replica set primary switch during a large collection scan; the embedded change-stream backfill task (error 424/425) failing underneath.

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

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