apache/seatunnel · error · HugeGraphConnectorException

GRAPH_OPERATION_FAILED

GRAPH_OPERATION_FAILED

Error message

Non-idempotent write failed (not retried to avoid duplicates): ${e.getMessage()}

What it means

executeNonIdempotentWrite runs insert operations that are not safe to retry (plain inserts could duplicate data). On ServerException or ClientException it immediately throws GRAPH_OPERATION_FAILED without retrying, to avoid duplicate writes.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/client/HugeGraphClient.java:211

     * createIfNotExist=true) and DELETE (removeVertex/removeEdge). Idempotent operations are
     * retried on retryable errors because a second attempt cannot create duplicates.
     */
    private void executeIdempotentWrite(GraphOperation operation) {
        executeGraphOperation(operation, true);
    }

    /**
     * Executes a write operation that is NOT safe to retry: plain INSERT (addVertex/addVertices/
     * addEdge/addEdges). A retry after a server-committed-but-client-timed-out response would
     * create a duplicate element. Non-idempotent writes fail fast — the caller's single-record
     * fallback handles them individually instead.
     */
    private void executeNonIdempotentWrite(GraphOperation operation) {
        try {
            ensureClientInitialized();
            operation.execute(this.client.graph());
        } catch (ServerException | ClientException e) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.GRAPH_OPERATION_FAILED,
                    "Non-idempotent write failed (not retried to avoid duplicates): "
                            + e.getMessage(),
                    e);
        }
    }

    /**
     * Executes a graph write with optional retry. When {@code idempotent} is true, retryable server
     * errors (status ≥ 500, 408, 425, 429) are retried up to {@code maxRetries} times with
     * exponential backoff. When false, the operation is attempted once — if it fails the exception
     * propagates immediately so the caller can route through the single-record fallback or skip the
     * record.
     */
    private void executeGraphOperation(GraphOperation operation, boolean idempotent) {
        int totalAttempts = idempotent ? this.maxRetries + 1 : 1;
        for (int attempt = 1; attempt <= totalAttempts; attempt++) {
            try {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped e.getMessage() to determine if it is a duplicate-id or schema error.
2. Use update strategies / idempotent write mode (e.g., create_if_absent/update_if_present) if re-submission is needed.
3. Pre-check existence or deduplicate records upstream to avoid duplicate-insert rejections.
4. Ensure schema constraints match the data being written.

Example fix

// before
// plain insert, fails on duplicates
client.writeVertex(vertex);
// after
// use update strategies so re-execution is idempotent
client.batchUpdateVertices(vertices, updateStrategies);

// deduplicate by id before writing non-idempotent inserts
Collection<Vertex> unique = records.stream()
    .collect(Collectors.toMap(Vertex::id, v -> v, (a, b) -> b)).values();

try {
    executeNonIdempotentWrite(op); // via connector sink
} catch (HugeGraphConnectorException e) {
    LOG.error("non-idempotent write failed, NOT retried: {}", e.getMessage(), e);
    throw e; // retrying here would duplicate data
}

When it happens

Trigger: writeVertex, writeEdge, batchWriteVertices, or batchWriteEdges hits a server/client exception during a non-idempotent insert (e.g., duplicate id with IF_ABSENT absent, schema violation, server error).

Common situations: Inserting a vertex/edge id that already exists; transient server errors that in this path are deliberately not retried; malformed element exceeding property constraints.

Related errors

• Graph operation failed on attempt {}/{}. Error: {}
• Mapping[VERTEX/{}] uses AUTOMATIC ids: under at-least-once d
• WRITER_OPERATION_FAILED
• Failed to write %d items to table %s after %d retries
• ADD_BATCH_DATA_FAILED

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