apache/seatunnel · error · IllegalStateException

Failed to list offsets for table

Error message

Failed to list offsets for table %s buckets %s

What it means

awaitOffsets waits on a CompletableFuture of per-bucket offsets (earliest/latest/bounds) from the Fluss admin. Any exceptional completion, timeout, or interruption is wrapped as 'Failed to list offsets for table <db.table> buckets [...]'.

Solutions

1. Check Fluss cluster health (coordinator + tablet servers) and that the table's buckets exist
2. Inspect the wrapped cause — timeout vs connection refused vs NoSuchBucketException point to different fixes
3. Increase the Fluss client request timeout if latency is the issue
4. Verify table name/bucket count config matches the actual cluster state

Example fix

// before
"scan.startup.mode" = "earliest" on table created without buckets
// after
CREATE TABLE mydb.orders (...) WITH ('bucket.num' = '3');  // ensure buckets exist before syncing

// verify table and buckets exist before reading offsets
TableInfo info = admin.getTableInfo(tablePath); // fails early with a clearer error
// assert bucketCount matches configured parallelism

try {
    Map<Integer, Long> offsets = awaitOffsets(future, tablePath, buckets);
} catch (SeaTunnelRuntimeException e) {
    if (isTransient(e.getCause())) { /* retry with backoff */ }
    else throw e; // bucket/table state problems are not retryable
}

When it happens

Trigger: The offsets future (from earliestOffsets/latestOffsets/bucketBounds) fails: Fluss coordinator/tablet server unreachable, table's buckets not yet created or deleted, request timeout, or thread interruption while future.get() blocks.

Common situations: Starting a source against a table that has no created buckets (new/empty table misconfig), cluster node down, or long request latency exceeding the client timeout under load.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Failed to close Fluss admin for
• Failed to read Fluss table info for
• Could not find existing binlog information while attempting…
• Does not support split requests: subtask
• Failed to close Fluss connection for

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-fluss/src/main/java/org/apache/seatunnel/connectors/seatunnel/fluss/source/FlussAdminClient.java:121

                listOffsetsAsync(tablePath, buckets, new OffsetSpec.LatestSpec());
        return new BucketBounds(
                awaitOffsets(earliest, tablePath, buckets),
                awaitOffsets(latest, tablePath, buckets));
    }

    private CompletableFuture<Map<Integer, Long>> listOffsetsAsync(
            TablePath tablePath, List<Integer> buckets, OffsetSpec spec) {
        return admin.listOffsets(toFlussTablePath(tablePath), buckets, spec).all();
    }

    private Map<Integer, Long> awaitOffsets(
            CompletableFuture<Map<Integer, Long>> future,
            TablePath tablePath,
            List<Integer> buckets) {
        try {
            return future.get();
        } catch (Exception e) {
            throw wrap(
                    String.format(
                            "Failed to list offsets for table %s buckets %s",
                            tablePath.getFullName(), buckets),
                    e);
        }
    }

    static final class BucketBounds {
        final Map<Integer, Long> earliest;
        final Map<Integer, Long> latest;

        BucketBounds(Map<Integer, Long> earliest, Map<Integer, Long> latest) {
            this.earliest = earliest;
            this.latest = latest;
        }
    }

    private static IllegalStateException wrap(String message, Exception e) {

View on GitHub (pinned to cf67b549a7)