apache/seatunnel · warning

Single-record fallback completed: {} succeeded, {} failed an

Error message

Single-record fallback completed: {} succeeded, {} failed and were skipped ({} skipped in total so far)

What it means

This WARN is logged by BatchBuffer.fallbackInsertSingly in the HugeGraph sink after a bulk write failed and every record was retried one-by-one. It reports how many records succeeded, how many were permanently skipped, and the running total of skipped records (insertFailureCount) for the task. It is a diagnostic summary, not an exception; the batch is not rethrown so the job can continue with dirty-data tolerance.

Source

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

                            HugeGraphConnectorErrorCode.GRAPH_OPERATION_FAILED,
                            String.format(
                                    "Aborting: cumulative single-insert failures (%d) reached "
                                            + "max_insert_errors (%d). Last error: %s",
                                    insertFailureCount, maxInsertErrors, single.getMessage()),
                            single);
                }
            }
        }
        if (failed == batch.size()) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.GRAPH_OPERATION_FAILED,
                    String.format(
                            "All %d record(s) in the batch failed single-insert fallback",
                            batch.size()),
                    lastFailure);
        }
        if (failed > 0) {
            LOG.warn(
                    "Single-record fallback completed: {} succeeded, {} failed and were skipped "
                            + "({} skipped in total so far)",
                    batch.size() - failed,
                    failed,
                    insertFailureCount);
        }
    }

    /**
     * Appends one line describing a skipped record — the mapped element's id/label/properties plus
     * the server error — to the per-subtask failure file when {@code failure_data_path} is set.
     * Best-effort: a write/open error disables further persistence rather than failing the task, so
     * a broken debug path can never mask the real insert failure.
     */
    private void writeFailureSample(GraphElementEnvelope envelope, Exception failure) {
        if (failureDataPath == null || failureDataPath.isEmpty() || failureWriterDisabled) {
            return;
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the failure-sample file written by writeFailureSample (failureDataPath) to see which records were skipped and why
2. Pre-create or align vertex/edge labels and property keys so records match the server schema
3. Fix or filter bad records upstream so the single-record fallback is not needed
4. Increase retry tolerance or fix connectivity if the underlying cause was transient server errors

Example fix

// before: letting bad rows silently skip
// after: validate schema before flush
if (!schemaCache.containsPropertyKey(propertyKey)) {
    createPropertyKeyIfNotExist(propertyKey); // ensures record won't fail single-insert
}

// Before writing, ensure schema exists so records don't fail single-insert
client.createVertexLabelIfNotExist(label, propertyKeys);
client.createEdgeLabelIfNotExist(sourceLabel, targetLabel, properties);

// Monitor via logs; enable failure-data persistence to audit skipped rows
// "failure-data-path" = "/ writable/dir/failures.log"
// After job: parse failure sample file and reprocess skipped records

When it happens

Trigger: A bulk vertex/edge insert via flushVertexGroup or flushEdgeGroup throws, the code falls back to inserting each record individually, and at least one single insert still fails (failed > 0). Common per-record causes: schema mismatch (missing vertex label/property key), constraint violation on edge, malformed property value, or transient server errors.

Common situations: Writing data whose properties don't match the HugeGraph schema, edge records referencing non-existent vertices, oversized batches hitting request limits, or the HugeGraph server partially rejecting records due to duplicates or serialization issues.

Related errors

• GRAPH_OPERATION_FAILED
• Failed to flush data during prepareCommit()
• INSERT_DOC_ERROR
• Batch write failed ({} element(s)); falling back to single-r
• Failed to persist failure sample to '{}'; disabling failure-

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