{"record":{"id":"72ac59a5871c63b4","repo":"apache/iceberg","slug":"staging-snapshot-s-on-branch-s-contains-a-v2-p-72ac59","errorCode":null,"errorMessage":"Staging snapshot %s on branch '%s' contains a V2 positional delete file (%s); equality delete conversion expects a V3 staging branch written by Flink, which produces only deletion vectors for deletes.","messagePattern":"Staging snapshot (.+?) on branch '(.+?)' contains a V2 positional delete file \\((.+?)\\); equality delete conversion expects a V3 staging branch written by Flink, which produces only deletion vectors for deletes\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/maintenance/operator/EqualityConvertPlanner.java","lineNumber":584,"sourceCode":"    for (DeleteFile deleteFile : changes.addedDeleteFiles()) {\n      if (deleteFile.content() == FileContent.EQUALITY_DELETES) {\n        Set<Integer> deleteFieldIds = Sets.newHashSet(deleteFile.equalityFieldIds());\n        Preconditions.checkState(\n            deleteFieldIds.equals(eqFieldIds),\n            \"Staging snapshot %s on branch '%s' contains an equality delete file %s with \"\n                + \"equalityFieldIds=%s, which does not match the configured eqFieldIds=%s. \"\n                + \"The writer must use the same equality field IDs as the converter.\",\n            stagingSnapshot.snapshotId(),\n            stagingBranch,\n            deleteFile.location(),\n            deleteFieldIds,\n            eqFieldIds);\n        validateDeleteSpecPartitionColumns(stagingSnapshot, deleteFile);\n        eqDeleteFiles.add(deleteFile);\n      } else if (ContentFileUtil.isDV(deleteFile)) {\n        stagingDVFiles.add(deleteFile);\n      } else {\n        throw new IllegalStateException(\n            String.format(\n                \"Staging snapshot %s on branch '%s' contains a V2 positional delete file (%s); \"\n                    + \"equality delete conversion expects a V3 staging branch written by Flink, \"\n                    + \"which produces only deletion vectors for deletes.\",\n                stagingSnapshot.snapshotId(), stagingBranch, deleteFile.location()));\n      }\n    }\n\n    return new StagingInputs(newDataFiles, stagingDVFiles, eqDeleteFiles);\n  }\n\n  private void validateDeleteSpecPartitionColumns(Snapshot stagingSnapshot, DeleteFile deleteFile) {\n    PartitionSpec spec = table.specs().get(deleteFile.specId());\n    for (PartitionField field : spec.fields()) {\n      Preconditions.checkState(\n          eqFieldIds.contains(field.sourceId()),\n          \"Staging snapshot %s on branch '%s' contains an equality delete file %s under spec %s, \"\n              + \"which partitions by field '%s' (source id %s) that is not an equality field %s. \"","sourceCodeStart":566,"sourceCodeEnd":602,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/maintenance/operator/EqualityConvertPlanner.java#L566-L602","documentation":"EqualityConvertPlanner.retrieveStagingFiles() expects the staging branch to be format-v3-style output of Flink writers producing only deletion vectors. If a staged delete file is a V2 positional delete file (neither an equality delete handled above nor a DV), it throws with the file location, since such files cannot be converted.","triggerScenarios":"The staging branch snapshot contains positional delete files — e.g. the table/branch is still format-version 2, or writers other than the Flink DV writer (Spark, older Flink writer) committed positional deletes to the staging branch.","commonSituations":"Table not upgraded to format-version 3 before running conversion; mixed-engine writes to the staging branch; fallback writer configuration emitting positional deletes instead of DVs; checkpoint restored data from a pre-upgrade snapshot.","solutions":["Upgrade the table to format-version 3 (ALTER TABLE ... SET TBLPROPERTIES ('format-version'='3')) and ensure writers produce DVs","Stop non-Flink or legacy writers from committing positional deletes to the staging branch","Set the Flink writer to emit deletion vectors (table property write.deletion-vectors.enabled=true) and re-run the cycle","Point conversion at a clean staging branch that only contains DV-producing commits"],"exampleFix":"// before\nALTER TABLE db.t SET TBLPROPERTIES ('format-version'='2')\n// after\nALTER TABLE db.t SET TBLPROPERTIES ('format-version'='3', 'write.deletion-vectors.enabled'='true')","handlingStrategy":"validation","validationCode":"// preflight before conversion\nif (table.properties().getOrDefault(\"format-version\", \"1\").compareTo(\"3\") < 0\n    || !\"true\".equals(table.properties().get(\"write.deletion-vectors.enabled\"))) {\n  throw new IllegalStateException(\"Staging branch must be V3 with DVs enabled\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Upgrade tables to format-version 3 before enabling equality-delete conversion","Enable write.deletion-vectors.enabled for all Flink writers","Prevent Spark/legacy writers from committing to the staging branch","Audit the staging branch's delete files (must be DVs only) before planning"],"tags":["format-version","positional-delete","deletion-vector","unsupported-operation","flink"],"backgroundTag":"unsupported-operation","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"}