apache/seatunnel · error · StarRocksConnectorException

FLUSH_DATA_FAILED

FLUSH_DATA_FAILED

Error message

Stream Load returned a non-success result for %s.%s with label [%s].

What it means

Thrown in StarRocksSinkManager.flush() when starrocksStreamLoadVisitor.doStreamLoad() completes but reports a non-success result (returns false instead of true). The sink retries the Stream Load up to maxRetries times, and each failed attempt raises this FLUSH_DATA_FAILED error. It indicates the load request reached StarRocks but StarRocks did not accept/commit it on that attempt.

Source

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

        checkFlushException();
        if (pendingFlush == null) {
            if (batchList.isEmpty()) {
                return;
            }
            pendingFlush =
                    new StarRocksFlushTuple(
                            createBatchLabel(), batchBytesSize, new ArrayList<>(batchList));
        }
        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(

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the StarRocks FE/BE logs for the label printed in the message to see the actual failure reason.
Increase sink max-retries and retry backoff options so transient publish timeouts are retried successfully.
Verify load_url points to reachable FE http ports and the database/table exist with a matching schema.
If errors persist, check disk space, BE status, and table replica health in StarRocks.

Example fix

// before: few retries, transient publish timeouts fail
sink = { max_retries = 1 }
// after: allow retries for transient failures
sink = { max_retries = 5, retry_backoff_multiplier_ms = 1000, max_retry_backoff_ms = 60000 }

Defensive patterns

Strategy: retry

Validate before calling

// pre-check target availability before flush
curl -s http://<fe-host>:8030/api/<db>/_stream_load_2pc || echo 'FE unreachable'
SHOW STREAM LOAD FROM <db>; // inspect recent label outcomes

Try / catch

try {
    sink.write(records);
} catch (StarRocksConnectorException e) {
    if (e.getErrorCode() == StarRocksConnectorErrorCode.FLUSH_DATA_FAILED) {
        // inspect label state, decide re-flush or replay from checkpoint
    }
}

Prevention

Configure generous max-retries and exponential backoff for transient StarRocks states
Monitor FE/BE health so publish timeouts are caught before they hit the sink
Keep labels unique per checkpoint to avoid ambiguous duplicate-label outcomes

When it happens

Trigger: doStreamLoad() returns Boolean.FALSE after a Stream Load HTTP round-trip whose reported status is not a success/commit state; flush() is invoked from write() when the batch buffer fills or from close() when the final batch is flushed.

Common situations: StarRocks returns a transient 'publish timeout' status; label state checks report a non-committed state; FE nodes under load reject or time out the load; wrong table schema causing 'Fail to get status' style responses.

Related errors

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