apache/iceberg · error · IllegalArgumentException

Unable to parse sortOrder: %s

Error message

Unable to parse sortOrder: %s

What it means

ExtendedParser.parseSortOrder delegates sort-order text to the Iceberg ExtendedParser SQL parser and wraps any resulting AnalysisException in this IllegalArgumentException. It means the supplied ORDER BY-style sort expression (e.g. for a write sort order) is not valid syntax. The original AnalysisException is chained as the cause.

Source

Thrown at spark/v4.1/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

1. Correct the sort-order string: it must be valid Spark SQL ORDER BY syntax (columns, Iceberg transforms like truncate(10, col), ASC/DESC, NULLS FIRST/LAST).
2. Reproduce the expression in `spark.sql("SELECT * FROM t ORDER BY <expr>")` to see the precise chained AnalysisException message.
3. Confirm the session parser is the Iceberg ExtendedParser (see the companion IllegalStateException error) by configuring the Iceberg extensions.

Example fix

// before
String order = "id DESC NULLS LASTZ";
// after
String order = "id DESC NULLS LAST";

// dry-run the sort expression before using it
try {
  spark.sql("SELECT * FROM t ORDER BY " + orderString).queryExecution().analyzed();
} catch (AnalysisException e) {
  throw new IllegalArgumentException("Invalid sort order: " + orderString, e);
}

try {
  SortOrder order = ExtendedParser.parseSortOrder(spark, orderString);
} catch (IllegalArgumentException e) {
  logger.error("Bad sort order: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
}

When it happens

Trigger: Calling SparkUtil/ExtendedParser.parseSortOrder(spark, orderString) with malformed SQL such as `id DESC NULLS LASTZ`, invalid transforms, or expressions the parser rejects; passing a bad 'sort-order' string via write options or table properties APIs.

Common situations: Copy-pasted sort expressions with typos; engine-version-specific syntax unsupported by the installed Spark parser; programmatically assembled SQL fragments that are invalid.

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

• Unable to parse sortOrder: %s
• Unable to parse sortOrder: %s
• Transform is not supported: ${transform}
• Cannot specify the 'sort-order' because it's a reserved tabl
• Cannot parse predicates in where option: ${where}

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