apache/iceberg · error · IllegalArgumentException

Invalid scan planning mode

Error message

Invalid scan planning mode: %s. Valid values are: %s

What it means

ScanPlanningMode.fromString resolves a configured mode name (e.g. sync vs async scan planning) to the enum. After a case-insensitive comparison against each mode's modeName() fails, it throws IllegalArgumentException listing the valid values.

Solutions

1. Use one of the listed valid mode names from the error message
2. Check the ScanPlanningMode enum in your Iceberg version for exact modeName() values
3. Match case-insensitively is supported, but fix spelling, not casing
4. Upgrade/downgrade the library if the mode you need is genuinely missing

Example fix

// before
Map.of("type", "rest", "rest.scan.planning-mode", "asynchronous")
// after
Map.of("type", "rest", "rest.scan.planning-mode", "async")

String mode = conf.get("rest.scan.planning-mode");
if (mode != null && Arrays.stream(ScanPlanningMode.values()).noneMatch(m -> m.modeName().equalsIgnoreCase(mode))) {
  throw new IllegalArgumentException("Unknown scan planning mode: " + mode);
}

try {
  planningMode = ScanPlanningMode.fromString(cfgValue);
} catch (IllegalArgumentException e) {
  planningMode = ScanPlanningMode.SYNC; // explicit default after logging
}

When it happens

Trigger: Setting the REST catalog property for scan planning mode to a misspelled or unsupported value (e.g. 'asynchronous' instead of the accepted mode names); copying a property value from docs of a different Iceberg version.

Common situations: Config typos in catalog properties; switching client versions where mode names changed; IDE-less hand-edited properties files.

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

• Cannot assume role to sign REST requests because is not…
• Cannot initialize AuthManager implementation
• Cannot support given S3 encryption type:
• Failed to create request URI from base
• Invalid codec name

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/RESTCatalogProperties.java:90

    REFS
  }

  public enum ScanPlanningMode {
    CLIENT,
    SERVER;

    public String modeName() {
      return name().toLowerCase(Locale.ROOT);
    }

    public static ScanPlanningMode fromString(String mode) {
      for (ScanPlanningMode planningMode : values()) {
        if (planningMode.modeName().equalsIgnoreCase(mode)) {
          return planningMode;
        }
      }

      throw new IllegalArgumentException(
          String.format(
              "Invalid scan planning mode: %s. Valid values are: %s",
              mode,
              Arrays.stream(values())
                  .map(ScanPlanningMode::modeName)
                  .collect(Collectors.joining(", "))));
    }
  }

  /**
   * The base URI of the remote signer endpoint. Optional, defaults to {@link
   * CatalogProperties#URI}.
   *
   * @deprecated since 1.12.0, will be removed in 1.13.0; there is no replacement
   */
  @Deprecated public static final String SIGNER_URI = "signer.uri";

  /**

View on GitHub (pinned to 86d9c8fc54)