apache/seatunnel · error · IcebergConnectorException

INVALID_STARTING_RECORD_OFFSET

INVALID_STARTING_RECORD_OFFSET

Error message

Invalid starting record offset %d

What it means

The inner reader's seek(startingRecordOffset) fast-forwards by repeatedly consuming hasNext()/next(). If the iterator is exhausted before reaching the requested offset, it throws IcebergConnectorException(INVALID_STARTING_RECORD_OFFSET). This means the restored offset points beyond the data available in this split's file.

Solutions

1. Don't run compaction/rewrite_data_files that replaces files still referenced by an in-flight streaming job; pause maintenance or restart the job from a fresh snapshot
2. Restart the job from the latest snapshot instead of the stale checkpoint offset
3. Verify the restored split still maps to the same immutable file (same path/length) — restore against the same table version/snapshot lineage

// Before resuming, confirm the split's file is unchanged
if (!split.file().path().equals(currentManifestEntry.file().path()) || split.file().fileSizeInBytes() != currentManifestEntry.file().fileSizeInBytes()) restartFromLatestSnapshot();

try { reader.seek(offset); } catch (IcebergConnectorException e) { if (e.getSeaTunnelErrorCode() == INVALID_STARTING_RECORD_OFFSET) { /* discard stale offset, restart from snapshot */ } throw e; }

When it happens

Trigger: Resuming a streaming/incremental read from a checkpoint whose starting record offset exceeds the number of records actually present in the split — e.g. the file was rewritten, compacted, or deleted and recreated between checkpoint and restore.

Common situations: Table maintenance (rewrite_data_files/compaction) removed or replaced files referenced by a restored checkpoint; restoring into a different table version; snapshot expiry plus rewrite producing shorter files.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• The restored committed-offset checkpoint does not contain…
• Cannot convert date:
• Cannot convert time:
• Cannot convert timestamp: , type:
• Cannot convert timestamptz: , type:

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/reader/IcebergFileScanTaskSplitReader.java:72

                    return seaTunnelRow;
                });
    }

    @Override
    public void close() {
        icebergFileScanTaskReader.close();
    }

    @AllArgsConstructor
    private static class OffsetSeekIterator<T> implements CloseableIterator<T> {
        private final CloseableIterator<T> iterator;

        public void seek(long startingRecordOffset) {
            for (long i = 0; i < startingRecordOffset; ++i) {
                if (hasNext()) {
                    next();
                } else {
                    throw new IcebergConnectorException(
                            IcebergConnectorErrorCode.INVALID_STARTING_RECORD_OFFSET,
                            String.format(
                                    "Invalid starting record offset %d", startingRecordOffset));
                }
            }
        }

        @Override
        public void close() throws IOException {
            iterator.close();
        }

        @Override
        public boolean hasNext() {
            return iterator.hasNext();
        }

        @Override

View on GitHub (pinned to cf67b549a7)