apache/iceberg · error · IllegalArgumentException

Unknown planning mode:

Error message

Unknown planning mode: 

What it means

PlanningMode.fromName converts a string (from the scan planning table property, e.g. 'local'/'distributed') into a PlanningMode enum constant and throws IllegalArgumentException for any other value. Only the exact (case-insensitive) mode names are accepted.

Solutions

1. Set the property to exactly 'local' or 'distributed' (case-insensitive).
2. Remove the property entirely to fall back to the default planning behavior.
3. Check for stray whitespace or copied characters in the property value.

Example fix

// before
ALTER TABLE t SET TBLPROPERTIES ('scan.planning-mode'='distributedd');
// after
ALTER TABLE t SET TBLPROPERTIES ('scan.planning-mode'='distributed');

String mode = props.get("scan.planning-mode");
if (mode != null && !mode.equalsIgnoreCase("local") && !mode.equalsIgnoreCase("distributed")) {
  throw new IllegalArgumentException("Unknown planning mode: " + mode);
}

try {
  PlanningMode.fromName(mode);
} catch (IllegalArgumentException e) {
  PlanningMode planningMode = null; // fall back to library default
}

When it happens

Trigger: Setting the table property 'scan.planning-mode' (or the equivalent config) to a misspelled or unsupported value such as 'distributedd', 'auto', or an empty string.

Common situations: Typos in TBLPROPERTIES / Flink table options when choosing local vs distributed planning; copying config from docs of a version that supports additional modes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid metrics mode:
• AboveMax has no value
• apply(value) is deprecated, use bind(Type).apply(value)
• apply(value) is deprecated, use bind(Type).apply(value)
• Backup table name cannot be specified

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/PlanningMode.java:47

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

  public static PlanningMode fromName(String modeName) {
    Preconditions.checkArgument(modeName != null, "Mode name is null");

    if (AUTO.modeName().equalsIgnoreCase(modeName)) {
      return AUTO;

    } else if (LOCAL.modeName().equalsIgnoreCase(modeName)) {
      return LOCAL;

    } else if (DISTRIBUTED.modeName().equalsIgnoreCase(modeName)) {
      return DISTRIBUTED;

    } else {
      throw new IllegalArgumentException("Unknown planning mode: " + modeName);
    }
  }

  public String modeName() {
    return modeName;
  }
}

View on GitHub (pinned to 86d9c8fc54)