{"record":{"id":"834e87afd851a930","repo":"apache/seatunnel","slug":"invalid-starting-record-offset","errorCode":"INVALID_STARTING_RECORD_OFFSET","errorMessage":"Invalid starting record offset %d","messagePattern":"Invalid starting record offset (.+?)","errorType":"error_code","errorClass":"IcebergConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/reader/IcebergFileScanTaskSplitReader.java","lineNumber":72,"sourceCode":"                    return seaTunnelRow;\n                });\n    }\n\n    @Override\n    public void close() {\n        icebergFileScanTaskReader.close();\n    }\n\n    @AllArgsConstructor\n    private static class OffsetSeekIterator<T> implements CloseableIterator<T> {\n        private final CloseableIterator<T> iterator;\n\n        public void seek(long startingRecordOffset) {\n            for (long i = 0; i < startingRecordOffset; ++i) {\n                if (hasNext()) {\n                    next();\n                } else {\n                    throw new IcebergConnectorException(\n                            IcebergConnectorErrorCode.INVALID_STARTING_RECORD_OFFSET,\n                            String.format(\n                                    \"Invalid starting record offset %d\", startingRecordOffset));\n                }\n            }\n        }\n\n        @Override\n        public void close() throws IOException {\n            iterator.close();\n        }\n\n        @Override\n        public boolean hasNext() {\n            return iterator.hasNext();\n        }\n\n        @Override","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/reader/IcebergFileScanTaskSplitReader.java#L54-L90","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Restart the job from the latest snapshot instead of the stale checkpoint offset","Verify the restored split still maps to the same immutable file (same path/length) — restore against the same table version/snapshot lineage"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before resuming, confirm the split's file is unchanged\nif (!split.file().path().equals(currentManifestEntry.file().path()) || split.file().fileSizeInBytes() != currentManifestEntry.file().fileSizeInBytes()) restartFromLatestSnapshot();","typeGuard":null,"tryCatchPattern":"try { reader.seek(offset); } catch (IcebergConnectorException e) { if (e.getSeaTunnelErrorCode() == INVALID_STARTING_RECORD_OFFSET) { /* discard stale offset, restart from snapshot */ } throw e; }","preventionTips":["Don't compact/rewrite files while streaming jobs reference them","Keep table maintenance windows separate from streaming reads","Restart from latest snapshot instead of stale checkpoints after rewrites"],"tags":["iceberg","offset","restore"],"backgroundTag":"value-out-of-range","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}