apache/seatunnel · error · HugeGraphConnectorException

BUFFER_ADD_FAILED

BUFFER_ADD_FAILED

Error message

BatchBuffer is already closed.

What it means

BatchBuffer.add is a synchronized method that appends a GraphElementEnvelope to the write buffer. If the buffer has already been closed (closed flag set during flushAndClose/close), any further add throws BUFFER_ADD_FAILED to prevent writing into a torn-down buffer.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/buffer/BatchBuffer.java:125

            boolean checkVertex,
            int maxInsertErrors,
            String failureDataPath,
            int subtaskIndex) {
        // batchIntervalMs remains in the public signature for source compatibility. Timer flush is
        // registered by HugeGraphSinkWriter with the engine instead of creating a connector thread.
        this.batchSize = batchSize;
        this.client = client;
        this.batchFailureFallback = batchFailureFallback;
        this.checkVertex = checkVertex;
        this.maxInsertErrors = maxInsertErrors;
        this.failureDataPath = failureDataPath;
        this.subtaskIndex = subtaskIndex;
        this.insertFailureCount = 0;
    }

    public synchronized void add(GraphElementEnvelope envelope) throws IOException {
        if (closed) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.BUFFER_ADD_FAILED,
                    "BatchBuffer is already closed.");
        }

        try {
            if (envelope.getElementType() == LabelType.VERTEX) {
                vertexBuffer.add(envelope);
                if (vertexBuffer.size() >= batchSize) {
                    doFlushVertices();
                }
            } else {
                edgeBuffer.add(envelope);
                if (edgeBuffer.size() >= batchSize) {
                    // Topology safety only matters when the server validates endpoints: with
                    // check_vertex=true, flush pending vertices before the edges so no edge is sent
                    // before its endpoints exist. With check_vertex=false the server already
                    // accepts
                    // orphan edges, so skip the forced (undersized) vertex flush and let the vertex

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check BatchBuffer.isClosed() before calling add, or ensure all adds happen before close/flushAndClose.
2. Fix the writer lifecycle so records are drained before the sink closes the buffer.
3. If writing multi-threaded, close the buffer only after all producer threads have finished (join/barrier).
4. Inspect earlier logs for a flush exception that closed the buffer mid-stream and address the root cause.

Example fix

// before
buffer.add(envelope);
// after
if (!buffer.isClosed()) {
    buffer.add(envelope);
} else {
    // route to dead-letter or fail the batch cleanly
}

// java: gate adds on state
if (buffer.isClosed()) { /* route elsewhere */ return; }
buffer.add(envelope);

try {
    buffer.add(envelope);
} catch (HugeGraphConnectorException e) {
    if (e.getErrorCode() == HugeGraphConnectorErrorCode.BUFFER_ADD_FAILED) {
        // buffer closed: stop producing, flush upstream, do not retry
    } else throw e;
}

When it happens

Trigger: Calling add(envelope) after close() or after a flush triggered close (e.g., writer still processing records after checkpoint/prepareCommit closed the buffer; concurrent producer threads racing with close).

Common situations: Sink writer emitting late records after snapshot close; exception in flush path that closed the buffer but the caller retries adds; multi-threaded writes without coordinating with the sink lifecycle.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• The split fetcher manager has closed.
• BigtableSourceSplitEnumerator already closed; cannot create
• BigtableSourceSplitEnumerator closed during client creation
• DataTypeChanger not reset
• Handler not reset

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