{"record":{"id":"8c01e4a708a1fd1b","repo":"apache/iceberg","slug":"unexpected-distribution-mode-8c01e4","errorCode":null,"errorMessage":"Unexpected distribution mode: ","messagePattern":"Unexpected distribution mode: ","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java","lineNumber":161,"sourceCode":"      case NONE:\n        return Distributions.unspecified();\n\n      case HASH:\n        if (table.spec().isPartitioned()) {\n          return Distributions.clustered(clustering(table));\n        } else {\n          return Distributions.clustered(FILE_CLUSTERING);\n        }\n\n      case RANGE:\n        if (table.spec().isPartitioned() || table.sortOrder().isSorted()) {\n          return Distributions.ordered(ordering(table));\n        } else {\n          return Distributions.ordered(EXISTING_ROW_ORDERING);\n        }\n\n      default:\n        throw new IllegalArgumentException(\"Unexpected distribution mode: \" + mode);\n    }\n  }\n\n  /** Builds requirements for merge-on-read DELETE, UPDATE, MERGE operations. */\n  public static SparkWriteRequirements positionDeltaRequirements(\n      Table table,\n      Command command,\n      DistributionMode mode,\n      boolean fanoutEnabled,\n      long advisoryPartitionSize) {\n\n    if (command == UPDATE || command == MERGE) {\n      Distribution distribution = positionDeltaUpdateMergeDistribution(table, mode);\n      SortOrder[] ordering = positionDeltaUpdateMergeOrdering(table, fanoutEnabled);\n      return new SparkWriteRequirements(distribution, ordering, advisoryPartitionSize);\n    } else {\n      Distribution distribution = positionDeltaDeleteDistribution(table, mode);\n      SortOrder[] ordering = fanoutEnabled ? EMPTY_ORDERING : POSITION_DELETE_ORDERING;","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L143-L179","documentation":"Thrown by SparkWriteUtil when building a Distribution for COPY-ON-WRITE DELETE/UPDATE/MERGE writes and the table's write distribution mode is not one of the handled values (NONE, HASH, RANGE, or ORDERED). Iceberg validates distribution modes eagerly so misconfiguration fails at plan time rather than producing wrongly shuffled writes.","triggerScenarios":"Calling copyOnWriteDeleteUpdateDistribution with a table whose write distribution mode property (write.distribution-mode) parses to a value outside the supported enum set, or a code path passing a custom/unknown SparkWriteUtil.DistributionMode.","commonSituations":"Typo or unsupported value in write.distribution-mode in table properties, a stale Spark extension writing newer mode values that an older Iceberg runtime does not know, or custom catalog defaults injecting an unexpected mode.","solutions":["Check the table's write.distribution-mode property and set it to one of none, hash, or range","Upgrade the Iceberg runtime to a version that supports the mode you configured","Remove the custom/default property override injecting the unknown mode"],"exampleFix":"// before\nALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='balanced');\n// after\nALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='hash');","handlingStrategy":"validation","validationCode":"String mode = table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE, TableProperties.WRITE_DISTRIBUTION_MODE_NONE);\nPreconditions.checkArgument(\n    mode.equals(TableProperties.WRITE_DISTRIBUTION_MODE_NONE) ||\n    mode.equals(TableProperties.WRITE_DISTRIBUTION_MODE_HASH) ||\n    mode.equals(TableProperties.WRITE_DISTRIBUTION_MODE_RANGE),\n    \"Unsupported write.distribution-mode: %s\", mode);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set write.distribution-mode to none/hash/range","Check table properties before running CoW DELETE/UPDATE/MERGE","Keep Iceberg runtime versions aligned with documented property values"],"tags":["spark","distribution-mode","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"}