apache/iceberg · error · UnsupportedOperationException

Unknown field ordinal:

Error message

Unknown field ordinal: 

What it means

GenericManifestFile.getByPos supports ordinals 0-15 (manifest path through firstRowId) and throws UnsupportedOperationException('Unknown field ordinal: ' + basePos) for anything else. The basePos comes from internalGet, which maps projected positions to base positions; an unknown basePos means the projection references a field beyond the manifest file struct known to this class.

Source

Thrown at core/src/main/java/org/apache/iceberg/GenericManifestFile.java:325

        return addedFilesCount;
      case 8:
        return existingFilesCount;
      case 9:
        return deletedFilesCount;
      case 10:
        return addedRowsCount;
      case 11:
        return existingRowsCount;
      case 12:
        return deletedRowsCount;
      case 13:
        return partitions();
      case 14:
        return keyMetadata();
      case 15:
        return firstRowId();
      default:
        throw new UnsupportedOperationException("Unknown field ordinal: " + basePos);
    }
  }

  @Override
  protected <T> void internalSet(int basePos, T value) {
    switch (basePos) {
      case 0:
        // always coerce to String for Serializable
        this.manifestPath = value.toString();
        return;
      case 1:
        this.length = (Long) value;
        return;
      case 2:
        this.specId = (Integer) value;
        return;
      case 3:
        this.content =

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg runtime to match the version that wrote the manifest list (field count must be <= supported ordinals).
2. Regenerate the projection via the actual manifest file type (ManifestFile.getType(...)) instead of a hand-written schema.
3. Identify the reported basePos and compare against the 16 known fields to find the unexpected projection field.

Example fix

// before
Schema projection = new Schema(manifestFileType.fields()); // includes unknown new fields
// after: project only supported fields
Schema projection = new Schema(manifestFileType.fields().stream()
    .filter(f -> f.fieldId() <= ManifestFile.FIRST_ROW_ID.fieldId())
    .collect(Collectors.toList()));

int fieldCount = projection.asStructType().fields().size();
if (fieldCount > 16) {
  throw new IllegalArgumentException("Projection has " + fieldCount + " fields; reader supports at most 16");
}

boolean isSupportedManifestFileOrdinal(int basePos) { return basePos >= 0 && basePos <= 15; }

try {
  ManifestFile mf = manifestReader.read();
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unknown field ordinal")) {
    // rebuild projection from ManifestFile.getType(...) and/or upgrade Iceberg
  } else throw e;
}

When it happens

Trigger: Reading a ManifestFile struct with a projection containing a field ordinal > 15 — e.g. manifests written by a newer spec/version with extra fields, or a hand-built projection schema for the 'manifests'/'files' metadata tables.

Common situations: Version skew: newer writer, older reader; custom metadata-table SQL/projections referencing added columns like first_row_id before/after upgrade; third-party tools constructing ManifestFile projections manually.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unknown field ordinal: ${basePos}
• Unknown field ordinal:
• Unknown field ordinal:
• Unknown field ordinal:
• Cannot copy

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