apache/seatunnel · critical · IOException

Failed to write ${bufferSize} vertices to NebulaGraph tag '$

Error message

Failed to write ${bufferSize} vertices to NebulaGraph tag '${tag}'. The writer will not retry this batch during close.

What it means

NebulaGraphSinkWriter.flush builds an nGQL request from the buffered vertices and executes it. On IOException or RuntimeException it marks the writer failed (failed=true, disabling retries during close), clears nothing, and throws an IOException reporting the batch size and target tag. The message warns the batch will not be retried during close to avoid duplicates/data issues.

Source

Thrown at seatunnel-connectors-v2/connector-nebulagraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/nebulagraph/sink/NebulaGraphSinkWriter.java:135

        } finally {
            closed = true;
        }
        if (failure != null) {
            throw failure;
        }
    }

    private void flush() throws IOException {
        if (buffer.isEmpty()) {
            return;
        }
        NebulaGraphWriteRequest request = statementBuilder.build(buffer);
        try {
            client.execute(request.getStatement(), request.getParameters());
            buffer.clear();
        } catch (IOException | RuntimeException e) {
            failed = true;
            throw new IOException(
                    "Failed to write "
                            + buffer.size()
                            + " vertices to NebulaGraph tag '"
                            + config.getTag()
                            + "'. The writer will not retry this batch during close.",
                    e);
        }
    }

    private void ensureWritable() throws IOException {
        if (closed) {
            throw new IOException("NebulaGraph sink writer is already closed.");
        }
        if (failed) {
            throw new IOException("NebulaGraph sink writer is in a failed state.");
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the cause chain for the underlying server/connection error
Verify the tag and property schema match (DESCRIBE TAG) and reduce batch size if limits are hit
Check Nebula cluster health (leader distribution, storaged status) and restore connectivity
After fixing, restart the job from the last successful checkpoint — this batch was marked failed and will not be retried in close()

Example fix

// before
tag = "Persn"
// after
tag = "Person" // must match DESCRIBE TAG output

Defensive patterns

Strategy: validation

Validate before calling

// preflight schema + connectivity
// USE my_space; DESCRIBE TAG my_tag;   -- tag/properties exist
// nc -zv <graphd-host> 9669            -- reachable

Try / catch

try {
    writer.write(row); // may throw on buffer-full flush
} catch (IOException e) {
    if (e.getMessage().contains("will not retry this batch during close")) {
        LOG.error("Batch of {} vertices dropped-failed; restart from checkpoint", bufferSize, e.getCause());
    }
    throw e;
}

Prevention

Validate tag schema against the cluster before deploying
Tune batch size below Nebula statement/data limits
Monitor session lifetime vs. job duration
Recover from checkpoints after this error — failed batches are not retried in close()

When it happens

Trigger: client.execute throws while flushing a non-empty vertex buffer — triggered from write() (buffer full), prepareCommit() (checkpoint), or close().

Common situations: Nebula unreachable or rejecting the batch (bad schema, leader change) at buffer-overflow time; oversized batch exceeding server limits; session expired mid-job; config tag name wrong.

Related errors

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