{"record":{"id":"70ca11ed796d1d78","repo":"apache/iceberg","slug":"unsupported-flag","errorCode":null,"errorMessage":"Unsupported flag: ","messagePattern":"Unsupported flag: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/puffin/PuffinReader.java","lineNumber":79,"sourceCode":"  }\n\n  public FileMetadata fileMetadata() throws IOException {\n    if (knownFileMetadata == null) {\n      int footerSize = footerSize();\n      byte[] footer = readInput(fileSize - footerSize, footerSize);\n\n      checkMagic(footer, PuffinFormat.FOOTER_START_MAGIC_OFFSET);\n      int footerStructOffset = footerSize - PuffinFormat.FOOTER_STRUCT_LENGTH;\n      checkMagic(footer, footerStructOffset + PuffinFormat.FOOTER_STRUCT_MAGIC_OFFSET);\n\n      PuffinCompressionCodec footerCompression = PuffinCompressionCodec.NONE;\n      for (Flag flag : decodeFlags(footer, footerStructOffset)) {\n        switch (flag) {\n          case FOOTER_PAYLOAD_COMPRESSED:\n            footerCompression = PuffinFormat.FOOTER_COMPRESSION_CODEC;\n            break;\n          default:\n            throw new IllegalStateException(\"Unsupported flag: \" + flag);\n        }\n      }\n\n      int footerPayloadSize =\n          PuffinFormat.readIntegerLittleEndian(\n              footer, footerStructOffset + PuffinFormat.FOOTER_STRUCT_PAYLOAD_SIZE_OFFSET);\n      Preconditions.checkState(\n          footerSize\n              == PuffinFormat.FOOTER_START_MAGIC_LENGTH\n                  + footerPayloadSize\n                  + PuffinFormat.FOOTER_STRUCT_LENGTH,\n          \"Unexpected footer payload size value %s for footer size %s\",\n          footerPayloadSize,\n          footerSize);\n\n      ByteBuffer footerPayload = ByteBuffer.wrap(footer, 4, footerPayloadSize);\n      ByteBuffer footerJson = PuffinFormat.decompress(footerCompression, footerPayload);\n      this.knownFileMetadata = parseFileMetadata(footerJson);","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/puffin/PuffinReader.java#L61-L97","documentation":"PuffinReader.fileMetadata encountered a footer flag it does not understand; only FOOTER_PAYLOAD_COMPRESSED is accepted, any other flag triggers this IllegalStateException. This guards against corrupt or forward-incompatible Puffin files, since flags describe footer handling the reader cannot safely apply.","triggerScenarios":"Reading a Puffin file whose decoded footer flags contain any Flag value other than FOOTER_PAYLOAD_COMPRESSED.","commonSituations":"Files written by newer Puffin writers introducing new flags; corrupted footers with garbage flag bytes; non-Puffin files misread as Puffin.","solutions":["Verify the file is a valid Puffin file from a compatible writer","Upgrade Iceberg so the reader recognizes newer flag values","Regenerate the file with a writer that does not set unsupported flags","Inspect the footer flags manually to identify the unexpected value"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Flags are only visible by parsing the footer; validate file provenance/writer version beforehand","typeGuard":null,"tryCatchPattern":"try {\n  PuffinReader.fileMetadata();\n} catch (IllegalStateException e) {\n  if (e.getMessage().startsWith(\"Unsupported flag\")) {\n    // upgrade Iceberg or reject the file\n  }\n}","preventionTips":["Match writer and reader Iceberg versions","Pin Iceberg versions across write/read paths","Only read puffin files from trusted, known writers"],"tags":["puffin","footer","forward-compatibility"],"backgroundTag":"unsupported-flag-value","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"}