apache/iceberg · error · IllegalStateException

Unsupported flag:

Error message

Unsupported flag: 

What it means

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.

Solutions

1. Verify the file is a valid Puffin file from a compatible writer
2. Upgrade Iceberg so the reader recognizes newer flag values
3. Regenerate the file with a writer that does not set unsupported flags
4. Inspect the footer flags manually to identify the unexpected value

// Flags are only visible by parsing the footer; validate file provenance/writer version beforehand

try {
  PuffinReader.fileMetadata();
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unsupported flag")) {
    // upgrade Iceberg or reject the file
  }
}

When it happens

Trigger: Reading a Puffin file whose decoded footer flags contain any Flag value other than FOOTER_PAYLOAD_COMPRESSED.

Common situations: Files written by newer Puffin writers introducing new flags; corrupted footers with garbage flag bytes; non-Puffin files misread as Puffin.

Related errors

• Cannot apply unknown table change:
• Cannot apply unsupported transform
• Cannot parse type as a reference: " + type
• Cannot process unknown snapshot operation
• Cannot process unknown snapshot operation

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/70ca11ed796d1d78. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/puffin/PuffinReader.java:79

  }

  public FileMetadata fileMetadata() throws IOException {
    if (knownFileMetadata == null) {
      int footerSize = footerSize();
      byte[] footer = readInput(fileSize - footerSize, footerSize);

      checkMagic(footer, PuffinFormat.FOOTER_START_MAGIC_OFFSET);
      int footerStructOffset = footerSize - PuffinFormat.FOOTER_STRUCT_LENGTH;
      checkMagic(footer, footerStructOffset + PuffinFormat.FOOTER_STRUCT_MAGIC_OFFSET);

      PuffinCompressionCodec footerCompression = PuffinCompressionCodec.NONE;
      for (Flag flag : decodeFlags(footer, footerStructOffset)) {
        switch (flag) {
          case FOOTER_PAYLOAD_COMPRESSED:
            footerCompression = PuffinFormat.FOOTER_COMPRESSION_CODEC;
            break;
          default:
            throw new IllegalStateException("Unsupported flag: " + flag);
        }
      }

      int footerPayloadSize =
          PuffinFormat.readIntegerLittleEndian(
              footer, footerStructOffset + PuffinFormat.FOOTER_STRUCT_PAYLOAD_SIZE_OFFSET);
      Preconditions.checkState(
          footerSize
              == PuffinFormat.FOOTER_START_MAGIC_LENGTH
                  + footerPayloadSize
                  + PuffinFormat.FOOTER_STRUCT_LENGTH,
          "Unexpected footer payload size value %s for footer size %s",
          footerPayloadSize,
          footerSize);

      ByteBuffer footerPayload = ByteBuffer.wrap(footer, 4, footerPayloadSize);
      ByteBuffer footerJson = PuffinFormat.decompress(footerCompression, footerPayload);
      this.knownFileMetadata = parseFileMetadata(footerJson);

View on GitHub (pinned to 86d9c8fc54)