{"record":{"id":"7597a4d03639589b","repo":"apache/iceberg","slug":"unsupported-distribution-mode-mode","errorCode":null,"errorMessage":"Unsupported distribution mode: mode","messagePattern":"Unsupported distribution mode: mode","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java","lineNumber":88,"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":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L70-L106","documentation":"SparkWriteUtil.writeDistribution() builds a Spark Distribution for a write based on the resolved DistributionMode. NONE and HASH/clustered and RANGE/ordered are handled; any other mode value throws IllegalArgumentException. This is a guard against an unexpected mode reaching the physical planning code.","triggerScenarios":"Calling SparkWriteUtil.writeDistribution(...) with a DistributionMode other than NONE, HASH, or RANGE — typically a future/unrecognized enum value or a mode resolved from a misconfigured write.distribution-mode property.","commonSituations":"Users set write.distribution-mode to a typo'd or unsupported value; custom catalogs/extensions resolve their own DistributionMode that this Spark version doesn't map to a Distribution.","solutions":["Set write.distribution-mode (or the operation-specific override) to one of none, hash, or range","Validate/normalize the mode string before it becomes a DistributionMode (SparkWriteConf already parses case-insensitively; check for typos)","Upgrade the Spark module if a new mode (e.g. from a newer spec) must be planned"],"exampleFix":"// before\nspark.conf.set(\"write.distribution-mode\", \"partitioned\")\n// after\nspark.conf.set(\"write.distribution-mode\", \"hash\")","handlingStrategy":"validation","validationCode":"String modeStr = spark.conf().get(\"write.distribution-mode\", \"none\").toLowerCase(Locale.ROOT);\nif (!Set.of(\"none\", \"hash\", \"range\").contains(modeStr)) {\n  throw new IllegalArgumentException(\"write.distribution-mode must be none, hash, or range\");\n}","typeGuard":"boolean isPlannableMode = mode == DistributionMode.NONE || mode == DistributionMode.HASH || mode == DistributionMode.RANGE;","tryCatchPattern":"try {\n  Distribution dist = SparkWriteUtil.writeDistribution(table, mode);\n} catch (IllegalArgumentException e) {\n  LOG.error(\"DistributionMode {} not supported by this Spark version\", mode);\n  throw e;\n}","preventionTips":["Use only none/hash/range for write.distribution-mode and its per-operation overrides","Normalize mode strings case-insensitively and reject unknown values early","Check release notes before using modes added in newer Iceberg versions"],"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"}