apache/iceberg · error · IllegalArgumentException

Unsupported distribution mode:

Error message

Unsupported distribution mode: 

What it means

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).

Source

Thrown at spark/v4.1/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. Set write.distribution-mode to a valid value: none, hash, or range
2. Validate/normalize the parsed DistributionMode before calling writeDistribution
3. Upgrade iceberg-spark if a newer DistributionMode constant must be handled

Example fix

// before
Distribution dist = SparkWriteUtil.writeDistribution(table, mode); // throws for unknown mode
// after
Preconditions.checkArgument(
    mode == DistributionMode.NONE || mode == DistributionMode.HASH || mode == DistributionMode.RANGE,
    "Unsupported distribution mode: %s", mode);
Distribution dist = SparkWriteUtil.writeDistribution(table, mode);

if (mode != DistributionMode.NONE && mode != DistributionMode.HASH && mode != DistributionMode.RANGE) {
  throw new IllegalArgumentException("Invalid write.distribution-mode: " + mode);
}

boolean isKnownDistributionMode(DistributionMode m) {
  return m == DistributionMode.NONE || m == DistributionMode.HASH || m == DistributionMode.RANGE;
}

try {
  dist = SparkWriteUtil.writeDistribution(table, mode);
} catch (IllegalArgumentException e) {
  LOG.warn("Unsupported mode {}, using unordered distribution", mode, e);
  dist = Distributions.unordered();
}

When it happens

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

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

Related errors

• Cannot parse order: parser is not an Iceberg ExtendedParser
• Cannot use catalog %s(%s): not a TableCatalog
• Invalid session catalog: sparkSessionCatalog
• Cannot parse order: parser is not an Iceberg ExtendedParser
• Invalid session catalog: ${sparkSessionCatalog}

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