apache/iceberg · error · UncheckedIOException

Decoding datum failed

Error message

Decoding datum failed

What it means

RawDecoder.decode wraps the InputStream in an Avro BinaryDecoder and delegates to the ValueReader. If the underlying read throws IOException, it is rethrown as UncheckedIOException("Decoding datum failed") with the original as cause. It means the encoded datum could not be read — usually corrupt or truncated data.

Source

Thrown at core/src/main/java/org/apache/iceberg/data/avro/RawDecoder.java:72

  }

  private final DatumReader<D> reader;

  /**
   * Creates a new {@link MessageDecoder} that constructs datum instances using the {@code reader}.
   */
  private RawDecoder(DatumReader<D> reader) {
    this.reader = reader;
  }

  @Override
  public D decode(InputStream stream, D reuse) {
    BinaryDecoder decoder = DecoderFactory.get().directBinaryDecoder(stream, DECODER.get());
    DECODER.set(decoder);
    try {
      return reader.read(reuse, decoder);
    } catch (IOException e) {
      throw new UncheckedIOException("Decoding datum failed", e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the cause IOException to determine truncation vs corruption.
2. Regenerate the data file/stream — the payload is likely truncated or corrupt.
3. Verify reader schema matches the schema used to encode the data.
4. Wrap decode in try-catch for UncheckedIOException and treat failed datums as poison records.

Example fix

// before
D d = rawDecoder.decode(stream, reuse); // UncheckedIOException on truncated data
// after
try {
  D d = rawDecoder.decode(stream, reuse);
} catch (UncheckedIOException e) {
  LOG.error("Datum decode failed", e.getCause());
  throw e;
}

null

null

try { return rawDecoder.decode(stream, reuse); } catch (UncheckedIOException e) { LOG.error("Decoding datum failed", e.getCause()); throw new CorruptDataException(e.getCause()); }

When it happens

Trigger: decode(stream, reuse) where the binary payload is truncated mid-record or the stream fails during value reading (closed stream, corrupt bytes, wrong schema version producing misaligned reads).

Common situations: Truncated files from incomplete writes; reading with a mismatched reader schema causing misparse; concurrent stream closure; corrupt network transfer.

Related errors

• Failed to read header and fingerprint bytes
• Cannot read manifest list file: %s
• Failed to create snapshot list writer for path: %s
• Cannot read manifest list file: %s
• Failed to close manifest reader

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