{"record":{"id":"fd9e64e340697359","repo":"apache/iceberg","slug":"unknown-field-ordinal-basepos","errorCode":null,"errorMessage":"Unknown field ordinal: ${basePos}","messagePattern":"Unknown field ordinal: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/BaseFile.java","lineNumber":445,"sourceCode":"        return keyMetadata();\n      case 14:\n        return splitOffsets();\n      case 15:\n        return equalityFieldIds();\n      case 16:\n        return sortOrderId;\n      case 17:\n        return firstRowId;\n      case 18:\n        return referencedDataFile;\n      case 19:\n        return contentOffset;\n      case 20:\n        return contentSizeInBytes;\n      case 21:\n        return fileOrdinal;\n      default:\n        throw new UnsupportedOperationException(\"Unknown field ordinal: \" + basePos);\n    }\n  }\n\n  @Override\n  public Object get(int pos) {\n    return get(pos, Object.class);\n  }\n\n  @Override\n  public int size() {\n    return DataFile.getType(EMPTY_STRUCT_TYPE).fields().size();\n  }\n\n  @Override\n  public Long pos() {\n    return fileOrdinal;\n  }\n","sourceCodeStart":427,"sourceCodeEnd":463,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/BaseFile.java#L427-L463","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the projection schema matches the expected DataFile/ManifestEntry schema ordinals (0..21)","Do not add extra top-level columns to projections of BaseFile-backed scans; nest them or extend BaseFile","Align Iceberg versions across writer/reader so field layouts match","Inspect the failing basePos value and map it to the schema field causing the mismatch"],"exampleFix":"// before\nTypes.StructType projection = Types.StructType.of(DATA_FILE_FIELDS, myExtraField); // ordinals beyond 21\n// after\nTypes.StructType projection = Types.StructType.of(DATA_FILE_FIELDS); // keep ordinals within BaseFile's supported fields\n","handlingStrategy":"validation","validationCode":"if (schema.columns().size() > 22) {\n  throw new IllegalStateException(\"Projection exceeds BaseFile-supported field ordinals (0..21)\");\n}","typeGuard":"boolean isKnownOrdinal(int pos) { return pos >= 0 && pos <= 21; }","tryCatchPattern":"try { Object v = dataFile.getByPos(pos); } catch (UnsupportedOperationException e) { /* ordinal not part of BaseFile's field layout */ }","preventionTips":["Keep projections within the standard DataFile/ManifestEntry schema","Don't add top-level custom columns to BaseFile-backed projections","Synchronize Iceberg versions so field layouts agree","Map custom fields to partition/spec-appropriate locations instead of new ordinals"],"tags":["schema","projection","ordinal"],"backgroundTag":"index-out-of-bounds","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}