{"record":{"id":"f173d0b657c6dfc7","repo":"apache/iceberg","slug":"unsupported-distribution-mode-f173d0","errorCode":null,"errorMessage":"Unsupported distribution mode: ","messagePattern":"Unsupported distribution mode: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/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.1/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L100-L136","documentation":"SparkWriteUtil.writeDistribution builds a Spark Distribution from a DistributionMode; the supported modes in this branch are HASH (clustered) and RANGE (ordered), with NONE handled earlier. Any other mode value reaches the default branch and throws IllegalArgumentException(\"Unsupported distribution mode: \" + mode).","triggerScenarios":"Invoking writeDistribution with a DistributionMode value not covered by the switch - typically an unexpected mode resolved from an unknown write.distribution-mode config string or a new enum constant.","commonSituations":"Misspelled or invalid write.distribution-mode table/job property producing an unexpected mode value; new DistributionMode constants added in newer Iceberg versions while this utility is older.","solutions":["Set write.distribution-mode to a valid value: none, hash, or range","Validate/normalize the parsed DistributionMode before calling writeDistribution","Upgrade iceberg-spark if a newer DistributionMode constant must be handled"],"exampleFix":"// before\nDistribution dist = SparkWriteUtil.writeDistribution(table, mode); // throws for unknown mode\n// after\nPreconditions.checkArgument(\n    mode == DistributionMode.NONE || mode == DistributionMode.HASH || mode == DistributionMode.RANGE,\n    \"Unsupported distribution mode: %s\", mode);\nDistribution dist = SparkWriteUtil.writeDistribution(table, mode);","handlingStrategy":"validation","validationCode":"if (mode != DistributionMode.NONE && mode != DistributionMode.HASH && mode != DistributionMode.RANGE) {\n  throw new IllegalArgumentException(\"Invalid write.distribution-mode: \" + mode);\n}","typeGuard":"boolean isKnownDistributionMode(DistributionMode m) {\n  return m == DistributionMode.NONE || m == DistributionMode.HASH || m == DistributionMode.RANGE;\n}","tryCatchPattern":"try {\n  dist = SparkWriteUtil.writeDistribution(table, mode);\n} catch (IllegalArgumentException e) {\n  LOG.warn(\"Unsupported mode {}, using unordered distribution\", mode, e);\n  dist = Distributions.unordered();\n}","preventionTips":["Configure write.distribution-mode only with none/hash/range","Parse mode values with case-insensitive, validated lookup","Fail fast on unknown config strings at session setup","Keep Iceberg versions aligned when DistributionMode gains constants"],"tags":["spark","distribution","configuration","invalid-value"],"backgroundTag":"unsupported-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"}