Mapping[VERTEX/{}] uses AUTOMATIC ids: under at-least-once d

Error message

Mapping[VERTEX/{}] uses AUTOMATIC ids: under at-least-once delivery a replayed row creates a duplicate vertex, and DELETE is not supported. Use PRIMARY_KEY or CUSTOMIZE_* ids for idempotent writes.

What it means

This warning is emitted by HugeGraphSinkWriter.buildMappingEntries() when a vertex mapping uses the AUTOMATIC id strategy. With AUTOMATIC ids the HugeGraph server assigns ids, so the writer cannot derive a dedup key from the row. Under SeaTunnel's at-least-once delivery, a replayed row after a retry creates a duplicate vertex, and DELETE events cannot be supported. The warning surfaces the trade-off so users can choose an idempotent id strategy.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/sink/HugeGraphSinkWriter.java:217

                LOG.info(
                        "Mapping[{}/{}] source_table '{}' does not match writer table '{}'; "
                                + "skipping in this writer.",
                        mapping.getType(),
                        mapping.getLabel(),
                        mapping.getSourceTable(),
                        tablePath);
                continue;
            }
            Map<String, Integer> fieldsIndex = resolveFieldsIndex(mapping, availableFieldsIndex);
            GraphDataMapper mapper;
            if (mapping.getType() == LabelType.VERTEX) {
                if (mapping.getIdStrategy()
                        == org.apache.hugegraph.structure.constant.IdStrategy.AUTOMATIC) {
                    // AUTOMATIC ids are server-assigned and not derivable from the row, so there is
                    // no key to deduplicate on: under at-least-once, a replayed row inserts a NEW
                    // vertex each time (duplicates). Warn so the trade-off is visible; use
                    // PRIMARY_KEY / CUSTOMIZE_* for idempotent upserts.
                    LOG.warn(
                            "Mapping[VERTEX/{}] uses AUTOMATIC ids: under at-least-once delivery a "
                                    + "replayed row creates a duplicate vertex, and DELETE is not "
                                    + "supported. Use PRIMARY_KEY or CUSTOMIZE_* ids for idempotent "
                                    + "writes.",
                            mapping.getLabel());
                }
                mapper = new VertexMapper(mapping, fieldsIndex, client);
            } else {
                mapper = new EdgeMapper(mapping, fieldsIndex, client);
            }
            entries.add(new MappingEntry(mapping, mapper));
        }

        if (entries.isEmpty()) {
            // Multi-table mode: at least one mapping has source_table, but none matched this
            // writer's tablePath. This is a configuration error — the user intended multi-table
            // but the table path strings don't align. Fail fast with a diagnostic that shows
            // both sides so the user can reconcile them.

View on GitHub (pinned to cf67b549a7)

Solutions

Change id_strategy to PRIMARY_KEY and designate the row field(s) that form the primary key, so replayed rows upsert instead of duplicating.
Or use CUSTOMIZE_NUMBER / CUSTOMIZE_STRING ids and map a row field that deterministically identifies the vertex.
If AUTOMATIC ids are truly required (pure append-only load), accept duplicates on replay or make the source idempotent; also avoid DELETE changelog modes.

Example fix

// before
mappings = [
  {type = "VERTEX", label = "person", id_strategy = "AUTOMATIC", properties = {name = "name"}}
]
// after
mappings = [
  {type = "VERTEX", label = "person", id_strategy = "PRIMARY_KEY", primary_keys = ["id"], properties = {id = "id", name = "name"}}
]

Defensive patterns

Strategy: validation

Validate before calling

mappings.each { m ->
    if (m.type == "VERTEX" && m.id_strategy == "AUTOMATIC") {
        println "WARNING: mapping ${m.label} uses AUTOMATIC ids; replayed rows will duplicate vertices"
    }
}

Prevention

Prefer PRIMARY_KEY or CUSTOMIZE_* id strategies for idempotent upserts
Design vertex schemas with a natural key derivable from the row
Remember SeaTunnel delivery is at-least-once; avoid non-idempotent sink configs for retryable jobs
Avoid AUTOMATIC ids when the pipeline may emit DELETE events

When it happens

Trigger: A VERTEX mapping has id_strategy resolving to IdStrategy.AUTOMATIC; buildMappingEntries() (called from the HugeGraphSinkWriter constructor) detects it during writer initialization.

Common situations: Configs that let vertices auto-id because no natural key exists; users unaware SeaTunnel guarantees at-least-once, so retries/replays after task restarts or checkpoint recovery duplicate vertices; downstream DELETE/sync scenarios that silently do not work.

Related errors

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