{"record":{"id":"06bf786548b13123","repo":"apache/iceberg","slug":"unsupported-format-version","errorCode":null,"errorMessage":"Unsupported format version: ","messagePattern":"Unsupported format version: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/MergingSnapshotProducer.java","lineNumber":314,"sourceCode":"    switch (formatVersion) {\n      case 1:\n        throw new IllegalArgumentException(\"Deletes are supported in V2 and above\");\n      case 2:\n        Preconditions.checkArgument(\n            file.content() == FileContent.EQUALITY_DELETES || !ContentFileUtil.isDV(file),\n            \"Must not use DVs for position deletes in V2: %s\",\n            ContentFileUtil.dvDesc(file));\n        break;\n      case 3:\n      case 4:\n        Preconditions.checkArgument(\n            file.content() == FileContent.EQUALITY_DELETES || ContentFileUtil.isDV(file),\n            \"Must use DVs for position deletes in V%s: %s\",\n            formatVersion,\n            file.location());\n        break;\n      default:\n        throw new IllegalArgumentException(\"Unsupported format version: \" + formatVersion);\n    }\n  }\n\n  private int formatVersion() {\n    return ops().current().formatVersion();\n  }\n\n  /** Add all files in a manifest to the new snapshot. */\n  protected void add(ManifestFile manifest) {\n    Preconditions.checkArgument(\n        manifest.content() == ManifestContent.DATA, \"Cannot append delete manifest: %s\", manifest);\n    if (canInheritSnapshotId() && manifest.snapshotId() == null) {\n      Preconditions.checkArgument(\n          manifest.firstRowId() == null,\n          \"Cannot append manifest with assigned first_row_id: %s\",\n          manifest.firstRowId());\n      appendedManifestsSummary.addedManifest(manifest);\n      appendManifests.add(manifest);","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/MergingSnapshotProducer.java#L296-L332","documentation":"Default branch of validateDeleteFileForVersion: the producer's format version is outside the handled set (1, 2, 3+). Since the switch only covers 1 and 2 in that branch, any other version value (e.g. a corrupted metadata formatVersion or a forward-compat case not yet implemented) lands here and throws this IllegalArgumentException.","triggerScenarios":"formatVersion() returns a value not covered by the switch (e.g. metadata formatVersion >= 4 not yet supported, or corrupted TableMetadata formatVersion) while validating delete files.","commonSituations":"Running an older Iceberg client against a table written by a newer writer with a higher format version; hand-edited/corrupted metadata JSON.","solutions":["Upgrade the Iceberg client/engine to a version supporting the table's format version","Check the table metadata's 'format-version' field for corruption or unexpected values","Recreate or migrate the table to a supported format version","Do not manually edit metadata files"],"exampleFix":"// before: old client reading newer table\n// iceberg-spark 3.3 with format-version=3 table\n// after: align client with table format version\n// upgrade to a release supporting format-version 3, or set 'format-version'='2' when writing the table","handlingStrategy":"validation","validationCode":"int v = table.ops().current().formatVersion();\nif (v != 1 && v != 2 && v != 3) throw new IllegalStateException(\"Unsupported table format version: \" + v + \"; upgrade the Iceberg client\");","typeGuard":null,"tryCatchPattern":"try { rowDelta.commit(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Unsupported format version\")) { /* upgrade client or migrate table */ } throw e; }","preventionTips":["Keep Iceberg client versions aligned with the newest format version writers in your org","Never hand-edit metadata JSON files","Validate format-version on table load in ingestion pipelines","Test forward compatibility when rolling out new format versions"],"tags":["format-version","forward-compatibility","validation"],"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-14T16:17:12.679Z"}