What causes "Unable to parse sortOrder: %s" in apache/iceberg?

Fix the ORDER BY string so it is valid Spark SQL (verify column names and expressions with a plain SELECT ... ORDER BY first)

apache/iceberg · error · IllegalArgumentException

Unable to parse sortOrder: %s

Error message

Unable to parse sortOrder: %s

What it means

ExtendedParser.parseSortOrder delegates order-string parsing (used by REWRITE DATA FILES / sort procedures) to the Iceberg ExtendedParser SQL parser. If parsing raises an AnalysisException, it is rethrown as IllegalArgumentException wrapping the original order string — meaning the SQL sort expression is invalid.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/ExtendedParser.java:63

      return term;
    }

    public SortDirection direction() {
      return direction;
    }

    public NullOrder nullOrder() {
      return nullOrder;
    }
  }

  static List<RawOrderField> parseSortOrder(SparkSession spark, String orderString) {
    ExtendedParser extParser = findParser(spark.sessionState().sqlParser(), ExtendedParser.class);
    if (extParser != null) {
      try {
        return extParser.parseSortOrder(orderString);
      } catch (AnalysisException e) {
        throw new IllegalArgumentException(
            String.format("Unable to parse sortOrder: %s", orderString), e);
      }
    } else {
      throw new IllegalStateException(
          "Cannot parse order: parser is not an Iceberg ExtendedParser");
    }
  }

  private static <T> T findParser(ParserInterface parser, Class<T> clazz) {
    ParserInterface current = parser;
    while (current != null) {
      if (clazz.isInstance(current)) {
        return clazz.cast(current);
      }

      current = getNextDelegateParser(current);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Fix the ORDER BY string so it is valid Spark SQL (verify column names and expressions with a plain SELECT ... ORDER BY first)
Check the chained AnalysisException cause for the precise parse error and column reference issue
Ensure the session parser is an Iceberg ExtendedParser (see the related IllegalStateException if not)

Example fix

// before
CALL catalog.system.rewrite_data_files(table => 'db.t', strategy => 'sort', sort_order => 'ts DESC, , id')
// after
CALL catalog.system.rewrite_data_files(table => 'db.t', strategy => 'sort', sort_order => 'ts DESC, id ASC')

Defensive patterns

Strategy: validation

Validate before calling

// validate the sort expression with plain SQL before passing it to the procedure
spark.sql("SELECT " + orderColumns + " FROM db.t ORDER BY " + orderString).explain(true);

Try / catch

try {
  callRewriteDataFiles(sortOrder);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unable to parse sortOrder")) {
    logger.error("Fix the ORDER BY string; cause: " + e.getCause(), e);
  } else { throw e; }
}

Prevention

Test the order string in a SELECT ... ORDER BY first
Check the chained AnalysisException for exact column/expression errors
Avoid trailing separators and unsupported functions in sort_order

When it happens

Trigger: Calling rewrite_data_files (or similar procedures) with an ORDER BY string that is not valid SQL in the current Spark session — misspelled column names, unsupported expressions, wrong quoting.

Common situations: Typos in column names; using functions unavailable in the session's SQL dialect; whitespace/quoting mistakes in the order string passed to the stored procedure.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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