{"record":{"id":"0d72b212dd6d9bb6","repo":"apache/iceberg","slug":"unsupported-distribution-mode-0d72b2","errorCode":null,"errorMessage":"Unsupported distribution mode: ","messagePattern":"Unsupported 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":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.2/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L100-L136","documentation":"SparkWriteUtil.writeDistribution builds a Spark Distribution from a DistributionMode. NONE is handled implicitly (unspecified), HASH yields clustered, RANGE yields ordered; any other mode value reaching the switch default throws IllegalArgumentException 'Unsupported distribution mode', meaning the configured/derived mode is not a recognized DistributionMode enum value.","triggerScenarios":"Calling SparkWriteUtil.writeDistribution with a mode other than NONE/HASH/RANGE, or a DistributionMode value that was corrupted/deserialized incorrectly, during Spark write requirement planning for Iceberg tables.","commonSituations":"Passing a custom or null-derived DistributionMode through custom write requirement builders; deserialization mismatch after upgrades where a new mode was added but the util switch wasn't updated.","solutions":["Only pass valid DistributionMode values (NONE, HASH, RANGE) into writeDistribution","Handle the mode before calling: map unknown modes to a supported one or reject earlier with a clear validation error","Upgrade Iceberg if a newly added DistributionMode needs support in this util"],"exampleFix":"// before\nDistribution dist = SparkWriteUtil.writeDistribution(table, someUnknownMode); // throws\n// after\nDistributionMode mode = someUnknownMode == null ? DistributionMode.NONE : someUnknownMode;\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\n    && mode != DistributionMode.HASH\n    && mode != DistributionMode.RANGE) {\n  throw new IllegalArgumentException(\"Unsupported distribution mode: \" + mode);\n}","typeGuard":"boolean isWritableMode(DistributionMode m) {\n  return m == DistributionMode.NONE || m == DistributionMode.HASH || m == DistributionMode.RANGE;\n}","tryCatchPattern":"try { dist = SparkWriteUtil.writeDistribution(table, mode); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Unsupported distribution mode\")) { dist = null; /* fall back to unspecified distribution */ } else throw e; }","preventionTips":["Only configure write distribution/order via known mode names (none/hash/range)","Validate mode config values before building requirements","Keep DistributionMode enum handling exhaustive in custom utils"],"tags":["spark","distribution","write-requirements","invalid-enum"],"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-23T08:17:48.524Z"}