apache/iceberg · error · RuntimeException

Unrecognized mode: " + mode

Error message

Unrecognized mode: " + mode

What it means

After decoding, readInteger dispatches on the current mode which must be RLE or PACKED; any other internal mode value is an invariant violation and throws RuntimeException. This means the decoder state machine is corrupted or misused.

Source

Thrown at arrow/src/main/java/org/apache/iceberg/arrow/vectorized/parquet/BaseVectorizedParquetValuesReader.java:241

  @Override
  public int readValueDictionaryId() {
    return readInteger();
  }

  @Override
  public int readInteger() {
    if (this.currentCount == 0) {
      this.readNextGroup();
    }

    this.currentCount--;
    switch (mode) {
      case RLE:
        return this.currentValue;
      case PACKED:
        return this.packedValuesBuffer[packedValuesBufferIdx++];
    }
    throw new RuntimeException("Unrecognized mode: " + mode);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Do not call readInteger/readBoolean out of order — drive the reader through its normal batch read API.
2. Check for custom subclasses that break the mode state machine.
3. If reproducible on standard reads, report it as a bug and fall back to non-vectorized reads.

// catch (RuntimeException e) {
//   if (e.getMessage() != null && e.getMessage().startsWith("Unrecognized mode")) {
//     reportBugAndFallbackToNonVectorized();
//   } else throw e;
// }

When it happens

Trigger: readInteger (also reached via readBoolean and readValueDictionaryId) when internal mode is neither RLE nor PACKED after readNextGroup.

Common situations: Reading values before the first readNextGroup call, or subclass misuse leaving the mode in an undefined state; rarely a corrupt page.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unsupported variant: shredded typed_value array
• Non-supported bytesWidth: " + bytesWidth
• not a valid mode " + this.mode
• Failed to read from input stream
• skip is not supported

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