apache/iceberg · error · UnsupportedOperationException

Unsupported shredded value type

Error message

Unsupported shredded value type: ${logical}

What it means

Thrown by VariantReaderBuilder's TimeLogicalTypeAnnotation visitor when a shredded Variant typed_value uses a TIME logical type that is not TIME_MICROS adjusted-to-UTC=false. The Parquet Variant spec only permits TIME (microsecond, non-UTC) for shredded time values; any other time encoding is rejected at reader construction.

Solutions

1. Rewrite the column as TIME(NANOS? no) TIME_MICROS with isAdjustedToUTC=false in typed_value, then read again.
2. Disable shredding (write the Variant unshredded) so the time value stays inside the variant binary instead of a typed Parquet column.
3. Fix the producing writer to emit TIME_MICROS non-UTC per the Parquet Variant shredding spec.
4. Filter out/ignore the shredded time field in reads that do not need it.

Example fix

// before
Types.required(PrimitiveTypeName.INT64).as(LogicalTypeAnnotation.timeType(true, TimeUnit.MICROS)).named("typed_value")

// after
Types.required(PrimitiveTypeName.INT64).as(LogicalTypeAnnotation.timeType(false, TimeUnit.MICROS)).named("typed_value")

LogicalTypeAnnotation l = typedValue.getType().asPrimitiveType().getLogicalTypeAnnotation();
if (l instanceof TimeLogicalTypeAnnotation t) {
  Preconditions.checkArgument(t.getUnit() == TimeUnit.MICROS && !t.isAdjustedToUTC(),
      "Shredded time must be TIME_MICROS non-UTC: %s", t);
}

boolean isVariantShreddableTime(LogicalTypeAnnotation l) {
  return l instanceof TimeLogicalTypeAnnotation t
      && t.getUnit() == TimeUnit.MICROS && !t.isAdjustedToUTC();
}

try {
  openVariantReader(schema);
} catch (UnsupportedOperationException e) {
  fallbackToUnshreddedRead();
}

When it happens

Trigger: visit(TimeLogicalTypeAnnotation) where logical.getUnit() != MICROS or logical.isAdjustedToUTC() is true while building a reader for a shredded Variant column.

Common situations: Writers shredding Variant time values as TIME_MILLIS or as isAdjustedToUTC=true timestamps; hand-authored schemas deviating from the Variant shredding spec; cross-ecosystem files where the writer used a different time convention.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Invalid bit width for int
• Invalid bit width for int
• Invalid primitive type for decimal
• Invalid primitive type for decimal
• Unknown primitive physical type

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/VariantReaderBuilder.java:222

      VariantValueReader reader =
          ParquetVariantReaders.asVariant(PhysicalType.DATE, ParquetValueReaders.unboxed(desc));

      return Optional.of(reader);
    }

    @Override
    public Optional<VariantValueReader> visit(TimestampLogicalTypeAnnotation logical) {
      VariantValueReader reader =
          ParquetVariantReaders.asVariant(
              ParquetVariantUtil.convert(logical), ParquetValueReaders.timestamps(desc));

      return Optional.of(reader);
    }

    @Override
    public Optional<VariantValueReader> visit(TimeLogicalTypeAnnotation logical) {
      if (logical.getUnit() != LogicalTypeAnnotation.TimeUnit.MICROS || logical.isAdjustedToUTC()) {
        throw new UnsupportedOperationException("Unsupported shredded value type: " + logical);
      }

      VariantValueReader reader =
          ParquetVariantReaders.asVariant(PhysicalType.TIME, ParquetValueReaders.times(desc));

      return Optional.of(reader);
    }

    @Override
    public Optional<VariantValueReader> visit(IntLogicalTypeAnnotation logical) {
      if (!logical.isSigned()) {
        // unsigned ints are not allowed for shredded fields
        throw new UnsupportedOperationException("Unsupported shredded value type: " + logical);
      }

      VariantValueReader reader;
      switch (logical.getBitWidth()) {
        case 64:

View on GitHub (pinned to 86d9c8fc54)