{"record":{"id":"88a903acc29c841a","repo":"apache/iceberg","slug":"invalid-file-expected-magic-at-offset-s-s-but","errorCode":null,"errorMessage":"Invalid file: expected magic at offset %s: %s, but got %s","messagePattern":"Invalid file: expected magic at offset (.+?): (.+?), but got (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/puffin/PuffinReader.java","lineNumber":154,"sourceCode":"                    input.seek(blobMetadata.offset());\n                    byte[] bytes = new byte[Math.toIntExact(blobMetadata.length())];\n                    ByteStreams.readFully(input, bytes);\n                    ByteBuffer rawData = ByteBuffer.wrap(bytes);\n                    PuffinCompressionCodec codec =\n                        PuffinCompressionCodec.forName(blobMetadata.compressionCodec());\n                    ByteBuffer data = PuffinFormat.decompress(codec, rawData);\n                    return Pair.of(blobMetadata, data);\n                  } catch (IOException e) {\n                    throw new UncheckedIOException(e);\n                  }\n                })\n            .iterator();\n  }\n\n  private static void checkMagic(byte[] data, int offset) {\n    byte[] read = Arrays.copyOfRange(data, offset, offset + MAGIC.length);\n    if (!Arrays.equals(read, MAGIC)) {\n      throw new IllegalStateException(\n          String.format(\n              \"Invalid file: expected magic at offset %s: %s, but got %s\",\n              offset, Arrays.toString(MAGIC), Arrays.toString(read)));\n    }\n  }\n\n  private int footerSize() throws IOException {\n    if (knownFooterSize == null) {\n      Preconditions.checkState(\n          fileSize >= PuffinFormat.FOOTER_STRUCT_LENGTH,\n          \"Invalid file: file length %s is less than minimal length of the footer tail %s\",\n          fileSize,\n          PuffinFormat.FOOTER_STRUCT_LENGTH);\n      byte[] footerStruct =\n          readInput(\n              fileSize - PuffinFormat.FOOTER_STRUCT_LENGTH, PuffinFormat.FOOTER_STRUCT_LENGTH);\n      checkMagic(footerStruct, PuffinFormat.FOOTER_STRUCT_MAGIC_OFFSET);\n","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/puffin/PuffinReader.java#L136-L172","documentation":"checkMagic validates that the expected Puffin magic bytes appear at a required offset (start of file, or computed footer start, depending on the caller: fileMetadata, footerSize). When the bytes do not match it throws this IllegalStateException reporting the offset, expected, and actual bytes. It means the file is not a valid Puffin file or the footer offset is wrong.","triggerScenarios":"Calling PuffinReader.fileMetadata or footerSize on a file whose leading bytes, or bytes at the computed footer start offset, do not equal the Puffin magic.","commonSituations":"Reading a non-Puffin file (e.g. plain Avro) as Puffin; truncated or corrupted files where the footer offset is miscalculated; files modified after writing.","solutions":["Confirm the file is a genuine Puffin file (it must begin with the Puffin magic)","Check for truncation/corruption; re-export or rewrite the file","Verify the file was not modified after writing (footer offset depends on trailing bytes)","Inspect bytes at the reported offset with a hex viewer"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"byte[] head = readFirstBytes(file, 4);\nif (!Arrays.equals(head, expectedPuffinMagic)) {\n  throw new IllegalArgumentException(\"Not a puffin file: \" + file);\n}","typeGuard":null,"tryCatchPattern":"try {\n  reader.fileMetadata();\n} catch (IllegalStateException e) {\n  if (e.getMessage().contains(\"expected magic\")) {\n    // treat as non-puffin file\n  }\n}","preventionTips":["Check magic bytes before parsing any file as Puffin","Verify file integrity (size, checksum) after transfer","Keep puffin files immutable after writing"],"tags":["puffin","magic-bytes","corrupt-file"],"backgroundTag":"checksum-mismatch","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}