{"record":{"id":"6d51e1bc10ce897c","repo":"apache/iceberg","slug":"unsupported-metadata-stats-field-id-statid","errorCode":null,"errorMessage":"Unsupported metadata stats field ID: ${statId}","messagePattern":"Unsupported metadata stats field ID: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/StatsUtil.java","lineNumber":110,"sourceCode":"\n  /**\n   * Return the field ID corresponding to the stats field ID.\n   *\n   * @param statId the field ID of a field stats struct or field within a stats struct\n   * @return ID of the corresponding table field\n   * @throws IllegalArgumentException if the stats ID is not valid\n   * @throws UnsupportedOperationException if the stats ID is for an unsupported metadata field\n   */\n  static int toFieldId(int statId) {\n    Preconditions.checkArgument(isValidStatId(statId), \"Invalid stats field ID: %s\", statId);\n\n    if (statId < CONTENT_STATS_RANGE_START) {\n      if (inBaseIdRange(LAST_UPDATED_SEQ_NUM_BASE_ID, statId)) {\n        return MetadataColumns.LAST_UPDATED_SEQUENCE_NUMBER.fieldId();\n      } else if (inBaseIdRange(ROW_ID_BASE_ID, statId)) {\n        return MetadataColumns.ROW_ID.fieldId();\n      } else {\n        throw new UnsupportedOperationException(\"Unsupported metadata stats field ID: \" + statId);\n      }\n    }\n\n    return (statId - CONTENT_STATS_RANGE_START) / NUM_RESERVED_FIELD_STATS_IDS;\n  }\n\n  /**\n   * Return the stats offset of a stats field ID.\n   *\n   * @param statId the field ID of a field stats struct or field within a stats struct\n   * @return offset that identifies the stored metric, or 0 for a stats struct's ID\n   * @throws IllegalArgumentException if the stats ID is not valid\n   * @throws UnsupportedOperationException if the stats ID is for an unsupported metadata field\n   */\n  static int statOffset(int statId) {\n    Preconditions.checkArgument(isValidStatId(statId), \"Invalid stats field ID: %s\", statId);\n\n    return statId % NUM_RESERVED_FIELD_STATS_IDS;","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/StatsUtil.java#L92-L128","documentation":"Stats files encode metadata column statistics using synthetic (reserved) field IDs that must fall into known ranges (last-updated-sequence-number, row-id, and content-stats ranges). toFieldId translates a stat ID back to a real field ID; an ID outside every known range cannot be mapped, so the parser refuses it. This protects forward compatibility: unknown reserved IDs mean the stats were written by a newer spec version the reader doesn't understand.","triggerScenarios":"Reading a stats (puffin/dv/placeholder-statistics) file whose metadata field statId is below CONTENT_STATS_RANGE_START but not within the LAST_UPDATED_SEQ_NUM or ROW_ID reserved ranges — i.e. StatsUtil.toFieldId(statId) called with an unrecognized reserved ID.","commonSituations":"Stats files written by a newer Iceberg version with additional reserved metadata stats IDs read by an older reader; hand-edited or corrupted stats files; custom tooling that invents stat IDs instead of using the spec-assigned ranges.","solutions":["Upgrade Iceberg to a version that knows the reserved stat ID range used by the stats file","Regenerate the stats file with a compatible writer so it only uses recognized stat IDs","Verify the stats file matches the table format version and spec you are reading with","Skip/ignore the unrecognized stats entries instead of failing plan if your use case tolerates missing stats"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"boolean knownReservedId(int statId) {\n  return statId >= CONTENT_STATS_RANGE_START\n      || inRange(LAST_UPDATED_SEQ_NUM_BASE_ID, statId)\n      || inRange(ROW_ID_BASE_ID, statId);\n}","typeGuard":null,"tryCatchPattern":"try { long fieldId = StatsUtil.toFieldId(statId); }\ncatch (UnsupportedOperationException e) {\n  LOG.warn(\"Unknown reserved stats ID {} from a newer writer; skipping\", statId);\n}","preventionTips":["Keep reader and writer Iceberg versions in sync across the deployment","Never hand-craft reserved stat IDs; use spec-assigned ranges only","Validate stats files after generation with a round-trip read","Treat unrecognized stat IDs as 'stats unavailable', not fatal, where possible"],"tags":["stats","field-id","forward-compatibility","iceberg"],"backgroundTag":"unsupported-enum-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}