apache/iceberg · error · IllegalArgumentException

unsupported strategy: + strategy + . Only binpack or sort is

Error message

unsupported strategy: + strategy + . Only binpack or sort is supported

What it means

RewriteDataFilesProcedure accepts only the rewrite strategies 'binpack' or 'sort' for the strategy option. Any other string reaches checkAndApplyStrategy's final else and throws IllegalArgumentException listing the accepted values. This is input validation of the strategy enum-like argument.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/procedures/RewriteDataFilesProcedure.java:204

                .flatMap(zOrder -> zOrder.refs().stream().map(NamedReference::name))
                .toArray(String[]::new);
        return action.zOrder(columnNames);
      } else if (!sortOrderFields.isEmpty()) {
        return action.sort(buildSortOrder(sortOrderFields, schema));
      } else {
        return action.sort();
      }
    }
    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 SortOrder buildSortOrder(
      List<ExtendedParser.RawOrderField> rawOrderFields, Schema schema) {
    SortOrder.Builder builder = SortOrder.builderFor(schema);
    rawOrderFields.forEach(
        rawField -> builder.sortBy(rawField.term(), rawField.direction(), rawField.nullOrder()));
    return builder.build();
  }

  private InternalRow[] toOutputRows(RewriteDataFiles.Result result) {
    int rewrittenDataFilesCount = result.rewrittenDataFilesCount();
    long rewrittenBytesCount = result.rewrittenBytesCount();
    int addedDataFilesCount = result.addedDataFilesCount();
    int failedDataFilesCount = result.failedDataFilesCount();
    int removedDeleteFilesCount = result.removedDeleteFilesCount();

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Use strategy => 'binpack' or strategy => 'sort' exactly (lowercase).
  2. Remove the strategy option entirely to use the default.
  3. For Z-order layout, use strategy => 'sort' with the z_order sort option instead of strategy => 'zorder'.
  4. Trim/normalize the value before invoking the procedure programmatically.

Example fix

-- before
CALL iceberg.system.rewrite_data_files(table => 'db.t', strategy => 'zorder');
-- after
CALL iceberg.system.rewrite_data_files(table => 'db.t', strategy => 'sort', z_order => 'col1,col2');
Defensive patterns

Strategy: validation

Validate before calling

if (!"binpack".equals(strategy) && !"sort".equals(strategy)) throw new IllegalArgumentException("strategy must be 'binpack' or 'sort', got: " + strategy);

Try / catch

try { rewriteDataFiles(..., strategy); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("unsupported strategy")) { /* use binpack or sort */ } else throw e; }

Prevention

When it happens

Trigger: CALL iceberg.system.rewrite_data_files(table => 'db.t', strategy => 'zorder') or strategy => 'compact' or 'SORT' (case-sensitive) — any value outside binpack/sort.

Common situations: Assuming 'zorder' is a valid strategy value (Zorder is configured via sort options, not strategy); misspellings like 'binpack ' with trailing space or 'bin-pack'; copying options from other engines (e.g. 'auto').

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