{"record":{"id":"a443f01872470f91","repo":"apache/iceberg","slug":"failed-reading-offset-from-s-a443f0","errorCode":null,"errorMessage":"Failed reading offset from: %s","messagePattern":"Failed reading offset from: (.+?)","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkMicroBatchStream.java","lineNumber":312,"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":294,"sourceCodeEnd":318,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkMicroBatchStream.java#L294-L318","documentation":"When resuming or advancing a Spark micro-batch streaming query, SparkMicroBatchStream.readOffset opens the stored offset file and parses it via StreamingOffset.fromJson. Any IOException while reading is rethrown as UncheckedIOException with the offset file location, indicating the stream could not recover its previous progress.","triggerScenarios":"Calling readOffset on a StreamingOffsetFileIO.InputFile whose stream cannot be opened or read — missing offset file, truncated/corrupt file, permission or network errors from the underlying FileIO.","commonSituations":"Checkpoint/offset files lost after table location changes or manual cleanup; partial writes from a previous crash; expired cloud credentials; offset location moved between runs.","solutions":["Restore the offset file at initialOffsetLocation from backup, or reset the streaming checkpoint and restart the query with a fresh initial offset","Fix the underlying storage access error surfaced in the chained IOException (permissions, credentials, connectivity)","Recreate the offset file contents (StreamingOffset JSON) if the snapshot/version it pointed to is still valid; otherwise use Spark's checkpoint recovery"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if (!file.exists()) {\n  throw new IllegalStateException(\"Offset file missing: \" + file.location());\n}","typeGuard":null,"tryCatchPattern":"try {\n  StreamingOffset offset = readOffset(file);\n} catch (UncheckedIOException e) {\n  LOG.error(\"Cannot read offset; resetting checkpoint\", e.getCause());\n  // fall back to initial offset or restore from backup\n}","preventionTips":["Never delete or relocate streaming offset/checkpoint files while a query runs","Back up offset files before maintenance","Ensure offset writes complete atomically to avoid corrupt partial files"],"tags":["spark","streaming","io","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"}