{"record":{"id":"0f3151cff372d577","repo":"apache/iceberg","slug":"unsupported-distribution-mode-mode-0f3151","errorCode":null,"errorMessage":"Unsupported distribution mode: ${mode}","messagePattern":"Unsupported 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":118,"sourceCode":"\n    Distribution distribution = writeDistribution(table, mode);\n    SortOrder[] ordering = writeOrdering(table, fanoutEnabled);\n    return new SparkWriteRequirements(distribution, ordering, advisoryPartitionSize);\n  }\n\n  private static Distribution writeDistribution(Table table, DistributionMode mode) {\n    switch (mode) {\n      case NONE:\n        return Distributions.unspecified();\n\n      case HASH:\n        return Distributions.clustered(clustering(table));\n\n      case RANGE:\n        return Distributions.ordered(ordering(table));\n\n      default:\n        throw new IllegalArgumentException(\"Unsupported distribution mode: \" + mode);\n    }\n  }\n\n  /** Builds requirements for copy-on-write DELETE, UPDATE, MERGE operations. */\n  public static SparkWriteRequirements copyOnWriteRequirements(\n      Table table,\n      Command command,\n      DistributionMode mode,\n      boolean fanoutEnabled,\n      long advisoryPartitionSize) {\n\n    if (command == DELETE || command == UPDATE) {\n      Distribution distribution = copyOnWriteDeleteUpdateDistribution(table, mode);\n      SortOrder[] ordering = writeOrdering(table, fanoutEnabled);\n      return new SparkWriteRequirements(distribution, ordering, advisoryPartitionSize);\n    } else {\n      return writeRequirements(table, mode, fanoutEnabled, advisoryPartitionSize);\n    }","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L100-L136","documentation":"SparkWriteUtil.writeDistribution maps an Iceberg DistributionMode (NONE, HASH, or RANGE) to a Spark Distribution. If the mode enum has a value outside those three, the switch falls through to default and throws IllegalArgumentException, indicating an internal mismatch between write config parsing and the distribution planner.","triggerScenarios":"Calling writeDistribution with a DistributionMode other than NONE/HASH/RANGE — e.g. a newly added enum constant not yet handled, or programmatic construction of a mode value that the utility does not cover.","commonSituations":"Running with a Spark/Iceberg version skew where write.distribution-mode resolves to a mode this SparkWriteUtil version does not implement; custom code passing an exotic DistributionMode directly.","solutions":["Check the write.distribution-mode table/session property resolves to none, hash, or range","Align the Iceberg runtime version across all Spark modules so DistributionMode and SparkWriteUtil come from the same release","If a new DistributionMode constant was added, add a case for it in the switch"],"exampleFix":"// before\nthrow new IllegalArgumentException(\"Unsupported distribution mode: \" + mode);\n// after\nswitch (mode) {\n  case NONE: return Distributions.unspecified();\n  case HASH: return Distributions.clustered(clustering(table));\n  case RANGE: return Distributions.ordered(ordering(table));\n  default: throw new IllegalArgumentException(\"Unsupported distribution mode: \" + mode);\n}","handlingStrategy":"validation","validationCode":"DistributionMode mode = DistributionMode.fromName(table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE, TableProperties.WRITE_DISTRIBUTION_MODE_DEFAULT));\nPreconditions.checkArgument(mode == DistributionMode.NONE || mode == DistributionMode.HASH || mode == DistributionMode.RANGE, \"Unsupported distribution mode: %s\", mode);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep write.distribution-mode to documented values (none/hash/range)","Pin a single Iceberg version across driver and executors","When adding DistributionMode constants, update all SparkWriteUtil switches"],"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"}