apache/iceberg · error · IllegalArgumentException

Unsupported distribution mode: ${mode}

Error message

Unsupported distribution mode: ${mode}

What it means

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.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java:118

    Distribution distribution = writeDistribution(table, mode);
    SortOrder[] ordering = writeOrdering(table, fanoutEnabled);
    return new SparkWriteRequirements(distribution, ordering, advisoryPartitionSize);
  }

  private static Distribution writeDistribution(Table table, DistributionMode mode) {
    switch (mode) {
      case NONE:
        return Distributions.unspecified();

      case HASH:
        return Distributions.clustered(clustering(table));

      case RANGE:
        return Distributions.ordered(ordering(table));

      default:
        throw new IllegalArgumentException("Unsupported distribution mode: " + mode);
    }
  }

  /** Builds requirements for copy-on-write DELETE, UPDATE, MERGE operations. */
  public static SparkWriteRequirements copyOnWriteRequirements(
      Table table,
      Command command,
      DistributionMode mode,
      boolean fanoutEnabled,
      long advisoryPartitionSize) {

    if (command == DELETE || command == UPDATE) {
      Distribution distribution = copyOnWriteDeleteUpdateDistribution(table, mode);
      SortOrder[] ordering = writeOrdering(table, fanoutEnabled);
      return new SparkWriteRequirements(distribution, ordering, advisoryPartitionSize);
    } else {
      return writeRequirements(table, mode, fanoutEnabled, advisoryPartitionSize);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Check the write.distribution-mode table/session property resolves to none, hash, or range
  2. Align the Iceberg runtime version across all Spark modules so DistributionMode and SparkWriteUtil come from the same release
  3. If a new DistributionMode constant was added, add a case for it in the switch

Example fix

// before
throw new IllegalArgumentException("Unsupported distribution mode: " + mode);
// after
switch (mode) {
  case NONE: return Distributions.unspecified();
  case HASH: return Distributions.clustered(clustering(table));
  case RANGE: return Distributions.ordered(ordering(table));
  default: throw new IllegalArgumentException("Unsupported distribution mode: " + mode);
}
Defensive patterns

Strategy: validation

Validate before calling

DistributionMode mode = DistributionMode.fromName(table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE, TableProperties.WRITE_DISTRIBUTION_MODE_DEFAULT));
Preconditions.checkArgument(mode == DistributionMode.NONE || mode == DistributionMode.HASH || mode == DistributionMode.RANGE, "Unsupported distribution mode: %s", mode);

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/0f3151cff372d577. Report an issue: GitHub.