apache/iceberg · error · UnsupportedOperationException

Unknown field ordinal: ${basePos}

Error message

Unknown field ordinal: ${basePos}

What it means

BaseFile's StructLike getByPos(int pos) maps fixed ordinals 0..21 to the data-file/manifest-entry fields; an ordinal outside that range hits the default branch and throws UnsupportedOperationException('Unknown field ordinal'). Callers passing a position derived from a schema that does not match BaseFile's expected field layout trigger this. Called from internalGet when reading file metadata fields positionally.

Source

Thrown at core/src/main/java/org/apache/iceberg/BaseFile.java:445

        return keyMetadata();
      case 14:
        return splitOffsets();
      case 15:
        return equalityFieldIds();
      case 16:
        return sortOrderId;
      case 17:
        return firstRowId;
      case 18:
        return referencedDataFile;
      case 19:
        return contentOffset;
      case 20:
        return contentSizeInBytes;
      case 21:
        return fileOrdinal;
      default:
        throw new UnsupportedOperationException("Unknown field ordinal: " + basePos);
    }
  }

  @Override
  public Object get(int pos) {
    return get(pos, Object.class);
  }

  @Override
  public int size() {
    return DataFile.getType(EMPTY_STRUCT_TYPE).fields().size();
  }

  @Override
  public Long pos() {
    return fileOrdinal;
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the projection schema matches the expected DataFile/ManifestEntry schema ordinals (0..21)
2. Do not add extra top-level columns to projections of BaseFile-backed scans; nest them or extend BaseFile
3. Align Iceberg versions across writer/reader so field layouts match
4. Inspect the failing basePos value and map it to the schema field causing the mismatch

Example fix

// before
Types.StructType projection = Types.StructType.of(DATA_FILE_FIELDS, myExtraField); // ordinals beyond 21
// after
Types.StructType projection = Types.StructType.of(DATA_FILE_FIELDS); // keep ordinals within BaseFile's supported fields

if (schema.columns().size() > 22) {
  throw new IllegalStateException("Projection exceeds BaseFile-supported field ordinals (0..21)");
}

boolean isKnownOrdinal(int pos) { return pos >= 0 && pos <= 21; }

try { Object v = dataFile.getByPos(pos); } catch (UnsupportedOperationException e) { /* ordinal not part of BaseFile's field layout */ }

When it happens

Trigger: Projecting a schema whose ordinal positions exceed BaseFile's known fields (e.g. custom metadata columns, newer spec fields not supported by the on-disk reader), or off-by-one schema construction in a projection.

Common situations: Custom scan projections adding columns beyond the standard 22 file fields; engine readers passing partition/column ordinals instead of BaseFile field ordinals; mixed Iceberg versions where the writer emitted extra fields.

Related errors

• Cannot find field %s in %s
• Unknown field ordinal:
• Unknown field ordinal:
• Unknown field ordinal:
• Unknown field ordinal:

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