apache/seatunnel · error · IllegalStateException

DocumentBulk is already full

Error message

DocumentBulk is already full

What it means

DocumentBulk.add throws IllegalStateException when the bulk already holds BUFFER_SIZE documents. This is an internal invariant guard: callers must flush and start a new DocumentBulk before adding more documents. It signals a programming/ordering bug in the writer's buffering logic, not a user-data problem.

Solutions

1. Check writer code paths that add documents: ensure flushToBulk/rollover creates a new DocumentBulk once size == BUFFER_SIZE.
2. Check size() or a hasSpace check before calling add(); call the flush path when the bulk is full.
3. If reproducible, file a bug with the job config and stack trace; this should never be reachable from normal sink usage.

Example fix

// before
bulk.add(document);
// after
if (bulk.size() >= DocumentBulk.getBufferSize()) {
    flushBulk();
}
bulk.add(document);

try {
    bulk.add(doc);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("already full")) {
        flushAndRotateBulk(); // then re-add
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling add(BsonDocument) on a DocumentBulk whose bufferedDocuments list already contains BUFFER_SIZE entries — i.e. the writer attempted to exceed the fixed internal buffer capacity without rolling over to a new bulk.

Common situations: Rare; indicates a bug in MongodbWriter's batch-rollover logic (isOverMaxBatchSizeLimit / flush ordering) or a misuse of the internal state class after a failed flush left the bulk full.

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

• Cannot extract clusterTime from change stream event…
• Change stream cursor has expired, trying to recreate cursor
• Collection does not appear to be sharded, fallback to…
• COMMON_ERROR_CODE.UNSUPPORTED_OPERATION
• Could not calculate standalone splits

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-mongodb/src/main/java/org/apache/seatunnel/connectors/seatunnel/mongodb/sink/state/DocumentBulk.java:50

 * size, typically 1,000 documents. But for the transactional mode, the maximum size should not be
 * respected because all that data must be written in one transaction.
 */
@ToString
@EqualsAndHashCode
public class DocumentBulk implements Serializable {

    public static final int BUFFER_SIZE = 1024;
    private static final long serialVersionUID = 7203410284346755522L;

    private final List<BsonDocument> bufferedDocuments;

    public DocumentBulk() {
        bufferedDocuments = new ArrayList<>(BUFFER_SIZE);
    }

    public void add(BsonDocument document) {
        if (bufferedDocuments.size() == BUFFER_SIZE) {
            throw new IllegalStateException("DocumentBulk is already full");
        }
        bufferedDocuments.add(document);
    }

    public int size() {
        return bufferedDocuments.size();
    }

    public List<BsonDocument> getDocuments() {
        return bufferedDocuments;
    }
}

View on GitHub (pinned to cf67b549a7)