apache/iceberg · error · IllegalArgumentException

unsupported strategy

Error message

unsupported strategy: %s. Only binpack or sort is supported

What it means

RewriteDataFilesProcedure validates the user-supplied 'strategy' option before building the rewrite action. Only 'binpack' and 'sort' are recognized strategy names; anything else (e.g. a typo like 'bin-pack', 'zorder', or uppercase 'BinPack') throws this IllegalArgumentException. The strategy controls how Iceberg rewrites compacted data files.

Solutions

Set strategy to exactly 'binpack' (default) or 'sort' in the procedure options map.
If you intended Z-order compaction, keep strategy='sort' and pass sort_order='zorder(col1,col2)' instead of strategy='zorder'.
Check the option value for typos and casing; the check is exact string comparison.
Consult the RewriteDataFilesSparkAction Strategy enum for valid names in your Iceberg version.

Example fix

// before
actions.rewriteDataFiles(t).option("strategy", "zorder").execute();
// after
actions.rewriteDataFiles(t)
    .option("strategy", "sort")
    .option("sort_order", "zorder(c1, c2)")
    .execute();

Defensive patterns

Strategy: validation

Validate before calling

Set<String> VALID = Set.of("binpack", "sort");
if (!VALID.contains(strategy)) {
    throw new IllegalArgumentException("strategy must be 'binpack' or 'sort', got: " + strategy);
}

Try / catch

try {
    SparkActions.get().rewriteDataFiles(table).option("strategy", strategy).execute();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("unsupported strategy")) { /* fix option and retry */ }
}

Prevention

Keep strategy values in a constants set shared with procedure invocation code
Remember comparison is case-sensitive; lowercase 'binpack'/'sort'
Express zorder/hilbert via sort_order, never as a strategy

When it happens

Trigger: Calling the rewrite_data_files Spark procedure with WHERE strategy = 'zorder' (as a strategy name rather than a sort expression), 'compaction', a misspelled value like 'binsort', or any value other than exactly 'binpack' or 'sort'. The strategy string is parsed in checkAndApplyStrategy before actions are built.

Common situations: Copy-pasting configs from older blog posts that reference strategy names that never existed; confusing the zorder/hilbert sort expression syntax with a strategy value; case mistakes ('Binpack') since the comparison is case-sensitive; migrating from other engines' compaction terminology (e.g. Delta's 'compact' optimization mode).

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/e1491c4974663557. Report an issue: GitHub.

Appendix: source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/procedures/RewriteDataFilesProcedure.java:182

    if (sortOrderString != null) {
      parseSortOrder(sortOrderString, zOrderTerms, hilbertTerms, sortOrderFields);
    }

    // caller of this function ensures that between strategy and sortOrder, at least one of them is
    // not null.
    if (strategy == null || strategy.equalsIgnoreCase("sort")) {
      return applySortStrategy(action, zOrderTerms, hilbertTerms, sortOrderFields, schema);
    }
    if (strategy.equalsIgnoreCase("binpack")) {
      RewriteDataFilesSparkAction binPackAction = action.binPack();
      if (sortOrderString != null) {
        // calling below method to throw the error as user has set both binpack strategy and sort
        // order
        return binPackAction.sort(buildSortOrder(sortOrderFields, schema));
      }
      return binPackAction;
    } else {
      throw new IllegalArgumentException(
          "unsupported strategy: " + strategy + ". Only binpack or sort is supported");
    }
  }

  private void parseSortOrder(
      String sortOrderString,
      List<Zorder> zOrderTerms,
      List<Hilbert> hilbertTerms,
      List<ExtendedParser.RawOrderField> sortOrderFields) {
    ExtendedParser.parseSortOrder(spark(), sortOrderString)
        .forEach(
            field -> {
              if (field.term() instanceof Zorder) {
                zOrderTerms.add((Zorder) field.term());
              } else if (field.term() instanceof Hilbert) {
                hilbertTerms.add((Hilbert) field.term());
              } else {
                sortOrderFields.add(field);

View on GitHub (pinned to 86d9c8fc54)