{"record":{"id":"09628b22aac5f0df","repo":"apache/iceberg","slug":"unsupported-distribution-mode","errorCode":null,"errorMessage":"Unsupported distribution mode: ","messagePattern":"Unsupported distribution mode: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java","lineNumber":176,"sourceCode":"      case NONE:\n        return Distributions.unspecified();\n\n      case HASH:\n        if (table.spec().isUnpartitioned()) {\n          return Distributions.clustered(concat(PARTITION_FILE_CLUSTERING, clustering(table)));\n        } else {\n          return Distributions.clustered(concat(PARTITION_CLUSTERING, clustering(table)));\n        }\n\n      case RANGE:\n        if (table.spec().isUnpartitioned()) {\n          return Distributions.ordered(concat(PARTITION_FILE_ORDERING, ordering(table)));\n        } else {\n          return Distributions.ordered(concat(PARTITION_ORDERING, ordering(table)));\n        }\n\n      default:\n        throw new IllegalArgumentException(\"Unsupported distribution mode: \" + mode);\n    }\n  }\n\n  private static SortOrder[] positionDeltaUpdateMergeOrdering(Table table, boolean fanoutEnabled) {\n    if (fanoutEnabled && table.sortOrder().isUnsorted()) {\n      return EMPTY_ORDERING;\n    } else {\n      return concat(POSITION_DELETE_ORDERING, ordering(table));\n    }\n  }\n\n  private static Distribution positionDeltaDeleteDistribution(Table table, DistributionMode mode) {\n    switch (mode) {\n      case NONE:\n        return Distributions.unspecified();\n\n      case HASH:\n        if (table.spec().isUnpartitioned()) {","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L158-L194","documentation":"positionDeltaUpdateMergeDistribution() builds the distribution for merge-on-read UPDATE/MERGE operations. Only NONE and HASH are planned here; any other DistributionMode (e.g. RANGE, if unsupported in this code path) hits the default branch and throws IllegalArgumentException. Note the message concatenates mode directly.","triggerScenarios":"Calling SparkWriteUtil.distribution() for a MoR UPDATE/MERGE where the resolved mode is not NONE or HASH — commonly write.merge.distribution-mode=range on a Spark version that doesn't support range distribution for positional deltas.","commonSituations":"Users copying CoW recommendations onto MoR operations; job configs with distribution-mode=range for merge operations on tables where it isn't planned.","solutions":["Set the merge/update distribution-mode to none or hash for merge-on-read operations","Drop the operation-specific property so it inherits a supported default","Upgrade the Spark module if range distribution for positional deltas is needed"],"exampleFix":"// before\nspark.conf.set(\"write.merge.distribution-mode\", \"range\")\n// after\nspark.conf.set(\"write.merge.distribution-mode\", \"hash\")","handlingStrategy":"validation","validationCode":"if (mode != DistributionMode.NONE && mode != DistributionMode.HASH) {\n  throw new IllegalArgumentException(\"MoR update/merge supports only none/hash, got \" + mode);\n}","typeGuard":"boolean moRUpdateMergeSupported = mode == DistributionMode.NONE || mode == DistributionMode.HASH;","tryCatchPattern":"try {\n  dist = SparkWriteUtil.positionDeltaUpdateMergeDistribution(table, mode, ...);\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"Unsupported merge distribution-mode for MoR: \" + mode, e);\n}","preventionTips":["Set write.merge.distribution-mode / write.update.distribution-mode to none or hash","Do not copy CoW range-mode configs onto merge-on-read operations","Pin the Spark module version and verify supported modes in its docs"],"tags":["spark","distribution-planning","illegal-argument"],"backgroundTag":"invalid-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"}