apache/iceberg · error · IllegalArgumentException

Invalid distribution mode: %s

Error message

Invalid distribution mode: %s

What it means

DistributionMode.fromName maps a string (typically from the write distribution mode table property) to the DistributionMode enum, case-insensitively. Unknown names and null both produce an IllegalArgumentException — null with message 'Invalid distribution mode: null', unknown values with 'Invalid distribution mode: <name>'.

Source

Thrown at api/src/main/java/org/apache/iceberg/DistributionMode.java:59

  HASH("hash"),
  RANGE("range");

  private final String modeName;

  DistributionMode(String modeName) {
    this.modeName = modeName;
  }

  public String modeName() {
    return modeName;
  }

  public static DistributionMode fromName(String modeName) {
    Preconditions.checkArgument(null != modeName, "Invalid distribution mode: null");
    try {
      return DistributionMode.valueOf(modeName.toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(String.format("Invalid distribution mode: %s", modeName));
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set the property to one of: none, hash, or range (case-insensitive).
2. Null-check/validate the config string before calling fromName, or use DistributionMode.fromName only after supplying a default.
3. Check the engine's accepted distribution mode values in docs for your Iceberg version; newer versions may add modes, but this parser only accepts enum names.
4. Fix the typo in the table property (SHOW TBLPROPERTIES / DESCRIBE TABLE to inspect).

Example fix

// before
tbl.setProperty("write.distribution-mode", "partition");

// after
tbl.setProperty("write.distribution-mode", "hash");

String mode = properties.get("write.distribution-mode");
Set<String> allowed = Set.of("none", "hash", "range");
if (mode != null && !allowed.contains(mode.toLowerCase(Locale.ROOT))) {
  throw new IllegalArgumentException("write.distribution-mode must be none|hash|range, got: " + mode);
}

DistributionMode dm;
try {
  dm = DistributionMode.fromName(mode);
} catch (IllegalArgumentException e) {
  dm = DistributionMode.NONE; // or surface config error to user
}

When it happens

Trigger: Setting write.distribution-mode (or engine equivalent) to a value other than none|hash|range (any case), e.g. 'None', 'key', 'partition', 'HASHING', or leaving a null value where a mode string is required.

Common situations: Typos in table properties; copying configs between engines with different valid values (e.g. Spark's 'fanout' style values); programmatic config where the property is absent so null is passed.

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

• Invalid file format: %s
• Cannot support given S3 encryption type:
• Unknown planning mode: ${mode}
• Unknown catalog type:
• Invalid isolation level: %s

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