{"record":{"id":"b7c5bc0a1ff466bc","repo":"apache/iceberg","slug":"unexpected-distribution-mode-mode-b7c5bc","errorCode":null,"errorMessage":"Unexpected distribution mode: ${mode}","messagePattern":"Unexpected distribution mode: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/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.0/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L143-L179","documentation":"copyOnWriteDeleteUpdateDistribution computes the distribution for copy-on-write DELETE/UPDATE/MERGE writes. Its switch over DistributionMode only handles NONE, HASH, and RANGE; any other value reaches default and throws IllegalArgumentException ('Unexpected distribution mode').","triggerScenarios":"Invoking the copy-on-write requirements builder when write.distribution-mode is set to a value the switch does not enumerate, or a version mismatch introducing a new DistributionMode constant.","commonSituations":"Version skew between iceberg-spark and iceberg-core jars on the classpath; misconfigured write.distribution-mode property with an unexpected parsed value.","solutions":["Set write.distribution-mode to none, hash, or range","Ensure a single consistent Iceberg version is on the Spark classpath","Extend the switch in copyOnWriteDeleteUpdateDistribution if a new mode was introduced"],"exampleFix":"// before\ndefault: throw new IllegalArgumentException(\"Unexpected distribution mode: \" + mode);\n// after\ndefault: throw new IllegalArgumentException(\"Unexpected distribution mode: \" + mode);\n// ensure callers pass only NONE/HASH/RANGE:\nPreconditions.checkArgument(mode == DistributionMode.NONE || mode == DistributionMode.HASH || mode == DistributionMode.RANGE, \"Mode %s not supported\", mode);","handlingStrategy":"validation","validationCode":"if (mode != DistributionMode.NONE && mode != DistributionMode.HASH && mode != DistributionMode.RANGE) { throw new IllegalArgumentException(\"Mode not supported for CoW delete/update: \" + mode); }","typeGuard":null,"tryCatchPattern":"try { requirements = SparkWriteUtil.copyOnWriteDeleteUpdateDistribution(table, mode, spec, fanout); } catch (IllegalArgumentException e) { LOG.error(\"Distribution mode rejected\", e); throw e; }","preventionTips":["Avoid version skew between iceberg-core and iceberg-spark jars","Use standard write.distribution-mode values","Review SparkWriteUtil switches when the DistributionMode enum changes"],"tags":["spark","illegal-argument","distribution-mode"],"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"}