apache/seatunnel · critical · StarRocksConnectorException

WRITE_RECORDS_FAILED

WRITE_RECORDS_FAILED

Error message

The number of retries was exceeded, writing records to StarRocks failed.

What it means

Thrown in StarRocksSinkManager.flush() when the retry loop exhausts sinkConfig.getMaxRetries() attempts to write records via Stream Load. The originating exception is attached as the cause. At this point the batch is definitively failed and the task will fail; buffered records are not delivered.

Source

Thrown at seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/client/StarRocksSinkManager.java:134

        StarRocksFlushTuple tuple = pendingFlush;
        boolean loadSucceeded = false;
        for (int i = 0; i <= sinkConfig.getMaxRetries(); i++) {
            try {
                Boolean successFlag = starrocksStreamLoadVisitor.doStreamLoad(tuple);
                if (Boolean.TRUE.equals(successFlag)) {
                    loadSucceeded = true;
                    break;
                }
                throw new StarRocksConnectorException(
                        StarRocksConnectorErrorCode.FLUSH_DATA_FAILED,
                        String.format(
                                "Stream Load returned a non-success result for %s.%s with label [%s].",
                                sinkConfig.getDatabase(), sinkConfig.getTable(), tuple.getLabel()));
            } catch (Exception e) {
                log.warn("Writing records to StarRocks failed, retry times = {}", i, e);

                if (i >= sinkConfig.getMaxRetries()) {
                    throw new StarRocksConnectorException(
                            StarRocksConnectorErrorCode.WRITE_RECORDS_FAILED,
                            "The number of retries was exceeded, writing records to StarRocks failed.",
                            e);
                }

                if (e instanceof StarRocksConnectorException
                        && ((StarRocksConnectorException) e).needReCreateLabel()) {
                    String newLabel = createBatchLabel();
                    log.warn(
                            String.format(
                                    "Batch label changed from [%s] to [%s]",
                                    tuple.getLabel(), newLabel));
                    tuple.setLabel(newLabel);
                }

                try {
                    long backoff =
                            Math.min(

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the wrapped cause ('Writing records to StarRocks failed, retry times = N' warnings) to find the root failure.
  2. Increase max-retries and backoff so longer StarRocks outages can be ridden out.
  3. Fix connectivity: verify load_url hosts, ports, firewalls, and DNS resolution.
  4. Ensure the target table exists and the row schema matches; fix and restart the job (checkpoint recovery will replay).
Defensive patterns

Strategy: try-catch

Validate before calling

// before job start
curl -s http://<fe>:8030/api/health
SHOW STREAM LOAD FROM <db>; // confirm cluster accepts loads

Try / catch

try {
    sink.close();
} catch (StarRocksConnectorException e) {
    if (e.getErrorCode() == StarRocksConnectorErrorCode.WRITE_RECORDS_FAILED) {
        log.error("Retries exhausted", e.getCause()); // root cause is in the cause chain
    }
}

Prevention

When it happens

Trigger: Every retry of doStreamLoad() throws (network errors, HTTP failures, non-success statuses) until i >= maxRetries; reached from write() (batch full) or close() (final flush).

Common situations: StarRocks cluster down or FE unreachable during the whole retry window; wrong load_url port; table locked or schema mismatch persisting across retries; long StarRocks ingestion backpressure.

Related errors

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