apache/iceberg · error · UnsupportedOperationException

Unknown field ordinal

Error message

Unknown field ordinal: ${i}

What it means

CommitToTable is an Avro-record event carrying a tableReference, snapshotId and validThroughTs; its StructLike get(i) resolves a field ordinal from the Avro schema to one of these values. An ordinal outside the known COMMIT-TO-TABLE fields throws UnsupportedOperationException('Unknown field ordinal'). This indicates the event's Avro schema layout does not match what this reader version expects.

Solutions

1. Use the same iceberg-kafka-connect-events version on producers and consumers.
2. Check the schema used to write the event (registry entry or embedded schema) matches CommitToTable's expected fields in order.
3. Re-serialize/replay historical events with the matching writer version if they predate a schema change.
4. Pin the Iceberg version in all Connect worker configs to avoid mixed-version deserialization.

Example fix

// before
// worker A: iceberg 1.4, worker B: iceberg 1.6 (mixed commit-event schemas)
// after
// both workers: iceberg 1.6 in connect-mirror-worker.properties:
// iceberg.version=1.6.0

// check embedded writer schema against expected field names/order
List<String> names = writerSchema.getFields().stream()
    .map(f -> f.name()).collect(Collectors.toList());
if (!names.equals(List.of("tableReference", "snapshotId", "validThroughTs"))) {
  throw new IllegalStateException("CommitToTable schema drift: " + names);
}

try {
  deserializeCommitToTable(record);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unknown field ordinal")) {
    // replay with reader matching the writer's Iceberg version, or skip to DLQ
    deadLetter(record, e);
  } else throw e;
}

When it happens

Trigger: Deserializing a CommitToTable event whose Avro schema has fields in a different order or extra/missing fields relative to the reader's schema — version skew between the event producer and consumer, or a schema registry entry that drifted from the code.

Common situations: Rolling upgrades of Kafka Connect iceberg sink workers with different Iceberg versions; replaying old commit events with a new reader; custom builds where the event schema was modified.

Related errors

• Unknown field ordinal
• The Avro schema is not a nullable type
• Unsupported type:
• Cannot coerce value to int:
• Cannot resolve schema for fingerprint:

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

Appendix: source

Thrown at kafka-connect/kafka-connect-events/src/main/java/org/apache/iceberg/connect/events/CommitToTable.java:140

        return;
      default:
        // ignore the object, it must be from a newer version of the format
    }
  }

  @Override
  public Object get(int i) {
    switch (AvroUtil.positionToId(i, avroSchema)) {
      case COMMIT_ID:
        return commitId;
      case TABLE_REFERENCE:
        return tableReference;
      case SNAPSHOT_ID:
        return snapshotId;
      case VALID_THROUGH_TS:
        return validThroughTs == null ? null : DateTimeUtil.microsFromTimestamptz(validThroughTs);
      default:
        throw new UnsupportedOperationException("Unknown field ordinal: " + i);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)