apache/seatunnel · error · StarRocksConnectorException

SCAN_BE_DATA_FAILED

SCAN_BE_DATA_FAILED

Error message

Failed to open scanner. + result.getStatus().getStatus_code() + result.getStatus().getError_msgs()

What it means

Thrown by StarRocksBeReadClient.openScanner when the `open_scanner` RPC to the StarRocks BE returns a non-OK TStatusCode. The BE refused to open the scan context, so no data can be read; the status code and BE error messages are appended to the exception message.

Solutions

Read the appended BE error_msgs to identify the exact reason (expired context, tablet not found, cancelled query).
Retry the job; transient BE states (restart, compaction) usually resolve.
Enable StarRocks source keep-alive tuning (keep_alive_min) for long scans, or reduce scan duration via smaller parallelism windows.
Verify the StarRocks user has SELECT privileges and the table schema is stable during the job.
Check FE logs for query cancellation and BE logs for scanner errors.

Defensive patterns

Strategy: retry

Validate before calling

// Pre-checks before long scans:
// SHOW TABLE STATUS LIKE '<table>';      -- stable schema
// GRANT SELECT ON <db>.* TO '<user>';    -- privileges
// Confirm BE capacity (memory) for batch_size in use

Try / catch

try {
    client.openScanner(params);
} catch (StarRocksConnectorException e) {
    if (isTransient(e)) { // e.g. context expired, tablet under compaction
        retryWithBackoff(3);
    } else {
        throw e;
    }
}

Prevention

Avoid DDL/schema changes on the table while the reading job runs.
Tune keep-alive and batch_size so scans finish before context expiry.
Ensure FE query timeouts exceed expected scan duration.
Monitor BE health; restarts break open scanners.

When it happens

Trigger: read -> openScanner: client.open_scanner(params) succeeds at the transport level but result.getStatus().getStatus_code() is not OK — e.g. the scan context (context_id from external service) expired, the query was cancelled, or the tablet/version was compacted or otherwise unavailable.

Common situations: Long-running scan whose keep-alive expired on the BE; BE restart or tablet migration mid-query; schema change on the table between plan and scan; insufficient privileges for the scan user; query timeout on the FE cancelling the external scan.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/client/source/StarRocksBeReadClient.java:117

        params.setTable(partition.getTable());
        params.setUser(sourceConfig.getUsername());
        params.setPasswd(sourceConfig.getPassword());
        params.setBatch_size(sourceConfig.getBatchRows());
        if (sourceConfig.getSourceOptionProps() != null) {
            params.setProperties(sourceConfig.getSourceOptionProps());
        }
        short keepAliveMin = (short) Math.min(Short.MAX_VALUE, sourceConfig.getKeepAliveMin());
        params.setKeep_alive_min(keepAliveMin);
        params.setQuery_timeout(sourceConfig.getQueryTimeoutSec());
        params.setMem_limit(sourceConfig.getMemLimit());
        log.info("open Scan params.mem_limit {} B", params.getMem_limit());
        log.info("open Scan params.keep-alive-min {} min", params.getKeep_alive_min());
        log.info("open Scan params.batch_size {}", params.getBatch_size());
        TScanOpenResult result = null;
        try {
            result = client.open_scanner(params);
            if (!TStatusCode.OK.equals(result.getStatus().getStatus_code())) {
                throw new StarRocksConnectorException(
                        StarRocksConnectorErrorCode.SCAN_BE_DATA_FAILED,
                        "Failed to open scanner."
                                + result.getStatus().getStatus_code()
                                + result.getStatus().getError_msgs());
            }
        } catch (TException e) {
            throw new StarRocksConnectorException(
                    StarRocksConnectorErrorCode.SCAN_BE_DATA_FAILED, e.getMessage());
        }
        this.contextId = result.getContext_id();
        log.info(
                "Open scanner for {}:{} with context id {}, and there are {} tablets {}",
                ip,
                port,
                contextId,
                tabletIds.size(),
                tabletIds);
        this.eos.set(false);

View on GitHub (pinned to cf67b549a7)