{"record":{"id":"a06494e0571d5ef5","repo":"apache/iceberg","slug":"failed-reading-offset-from-initialoffsetlocatio","errorCode":null,"errorMessage":"Failed reading offset from: ${initialOffsetLocation}","messagePattern":"Failed reading offset from: (.+?)","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/SparkMicroBatchStream.java","lineNumber":310,"sourceCode":"    }\n\n    private void writeOffset(StreamingOffset offset, OutputFile file) {\n      try (OutputStream outputStream = file.create()) {\n        BufferedWriter writer =\n            new BufferedWriter(new OutputStreamWriter(outputStream, StandardCharsets.UTF_8));\n        writer.write(offset.json());\n        writer.flush();\n      } catch (IOException ioException) {\n        throw new UncheckedIOException(\n            String.format(\"Failed writing offset to: %s\", initialOffsetLocation), ioException);\n      }\n    }\n\n    private StreamingOffset readOffset(InputFile file) {\n      try (InputStream in = file.newStream()) {\n        return StreamingOffset.fromJson(in);\n      } catch (IOException ioException) {\n        throw new UncheckedIOException(\n            String.format(\"Failed reading offset from: %s\", initialOffsetLocation), ioException);\n      }\n    }\n  }\n}\n","sourceCodeStart":292,"sourceCodeEnd":316,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/SparkMicroBatchStream.java#L292-L316","documentation":"readOffset streams the previously written offset JSON and parses it with StreamingOffset.fromJson. An IOException while reading is wrapped as UncheckedIOException naming initialOffsetLocation, so a corrupt/unreadable offset file stops the stream rather than silently resuming wrong.","triggerScenarios":"initialOffset() (or batch resume) calling readOffset when the offset file at initialOffsetLocation cannot be opened or fully read (missing file, transient storage error, truncation).","commonSituations":"Checkpoint location on flaky object storage, files deleted by retention/cleanup policies, or partially written offsets after an abrupt job kill.","solutions":["Check the cause for whether the file is missing or truncated; restore the checkpoint location from backup.","Verify the streaming checkpoint path was not removed by lifecycle/cleanup rules.","If the offset is unrecoverable, reset the stream with a new checkpoint dir or Spark's streaming checkpoint recovery options."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// check offset file exists and is non-empty before resume\nif (table.io().newInputFile(initialOffsetLocation).getLength() == 0) { /* recover checkpoint */ }","typeGuard":null,"tryCatchPattern":"try { offset = readOffset(file); } catch (UncheckedIOException e) { recoverOrResetCheckpoint(e.getCause()); }","preventionTips":["Back up checkpoint directories; restore on corruption","Do not apply retention/cleanup policies to streaming checkpoint locations","Avoid abrupt kills; use structured streaming graceful stop"],"tags":["spark","streaming","io","offset-checkpoint"],"backgroundTag":"file-read-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}