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.

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

• BigtableSourceSplitEnumerator already closed; cannot create…
• BigtableSourceSplitEnumerator closed during client creation
• The split fetcher manager has closed.
• Batch write failed ( element(s)); falling back to…
• Both 'mappings' and 'schema_config' are present…

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

Appendix: 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)