apache/iceberg · error · IllegalStateException

Unknown type for int field. Type name: ${className}

Error message

Unknown type for int field. Type name: ${className}

What it means

StructRowData.getInt(pos) converts an Iceberg internal value at a field position into a Flink int. It accepts Integer, Short, Byte, LocalDate (epoch day), and LocalTime (millis of day); any other runtime class triggers IllegalStateException 'Unknown type for int field'.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/data/StructRowData.java:129

  }

  @Override
  public short getShort(int pos) {
    return (short) (int) struct.get(pos, Integer.class);
  }

  @Override
  public int getInt(int pos) {
    Object integer = struct.get(pos, Object.class);

    if (integer instanceof Integer) {
      return (int) integer;
    } else if (integer instanceof LocalDate localDate) {
      return (int) localDate.toEpochDay();
    } else if (integer instanceof LocalTime) {
      return (int) (((LocalTime) integer).toNanoOfDay() / 1000_000);
    } else {
      throw new IllegalStateException(
          "Unknown type for int field. Type name: " + integer.getClass().getName());
    }
  }

  @Override
  public long getLong(int pos) {
    Object longVal = struct.get(pos, Object.class);

    if (longVal instanceof Long) {
      return (long) longVal;
    } else if (longVal instanceof OffsetDateTime) {
      return Duration.between(Instant.EPOCH, (OffsetDateTime) longVal).toNanos() / 1000;
    } else if (longVal instanceof LocalDate) {
      return ((LocalDate) longVal).toEpochDay();
    } else if (longVal instanceof LocalTime) {
      return ((LocalTime) longVal).toNanoOfDay();
    } else if (longVal instanceof LocalDateTime) {
      return Duration.between(Instant.EPOCH, ((LocalDateTime) longVal).atOffset(ZoneOffset.UTC))

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the Iceberg schema field is actually an int (Types.IntegerType) matching the Flink INT field; fix the schema mapping if not.
2. Log the offending class from the message and check which reader produced the value; use a reader that produces the expected representation.
3. Cast/convert the value in the custom reader (e.g. FlinkValueReaders) so ints are produced as Integer.
4. Align writer/reader Iceberg versions so internal value representations match.

Example fix

// before: field declared INT but reader emits Long
schema.add("v", Types.LongType.get()); // Flink expects INT
// after
schema.add("v", Types.IntegerType.get()); // matches StructRowData.getInt expectations

if (!(v instanceof Integer || v instanceof Short || v instanceof Byte || v instanceof LocalDate || v instanceof LocalTime)) {
  throw new IllegalArgumentException("value not int-compatible: " + v.getClass());
}

boolean isIntCompatible(Object v) {
  return v instanceof Integer || v instanceof Short || v instanceof Byte
      || v instanceof LocalDate || v instanceof LocalTime;
}

try {
  int i = structRow.getInt(pos);
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unknown type for int field")) {
    // fix schema mapping or convert value before projection
  }
}

When it happens

Trigger: Reading a struct field whose stored value class does not match the projected Flink RowType's int field - e.g. a Long, String, or Temporal value where an int was expected due to a schema/type mismatch between the Iceberg schema and the Flink type.

Common situations: Mismatched FlinkSchema conversion (declared INT in Flink but Iceberg holds a long or date value); reading data written by a different writer version with different internal representations (e.g. LocalTime vs millis); custom readers producing unexpected value classes.

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

• Unknown type for long field. Type name: ${className}
• Unknown type for timestamp_ns: ${class}
• Unknown type for binary field. Type name: ${className}
• Unknown type for int field. Type name: ${integer.getClass().
• Unknown type for long field. Type name: ${longVal.getClass()

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