apache/iceberg · error · java.lang.IllegalArgumentException

Unable to parse sortOrder: %s

Error message

Unable to parse sortOrder: %s

What it means

parseSortOrder parses an ORDER BY-like string for Iceberg DDL (e.g. WRITE ORDERED BY). If the wrapped Spark SQL parser (an Iceberg ExtendedParser) throws AnalysisException, it is rethrown as IllegalArgumentException 'Unable to parse sortOrder: <orderString>'.

Source

Thrown at spark/v4.2/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. Fix the order expression: use valid column names and supported directions (ASC/DESC, NULLS FIRST/LAST)
2. Quote/reserve identifiers if needed and reference only existing columns
3. Ensure the session SQL parser is the Iceberg ExtendedParser (extensions enabled: spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSqlExtensions)
4. Check nested-field notation (a.b.c) matches the actual schema

Example fix

// before
ALTER TABLE t WRITE ORDERED BY unknow_col
// after
ALTER TABLE t WRITE ORDERED BY known_col DESC NULLS LAST

// ensure columns exist before building order string
List<String> missing = cols.stream().filter(c -> !schema.existsField(c)).collect(Collectors.toList());
if (!missing.isEmpty()) throw new IllegalArgumentException("Unknown sort columns: " + missing);

try {
  sql(String.format("ALTER TABLE %s WRITE ORDERED BY %s", table, order));
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unable to parse sortOrder")) {
    log.error("Fix order expression syntax/columns: {}", order, e.getCause());
  } else throw e;
}

When it happens

Trigger: ALTER TABLE ... WRITE ORDERED BY <expr> or CREATE TABLE ... ORDERED BY with syntactically invalid sort expressions (bad column names, unsupported syntax).

Common situations: Misspelled column names in sort order; using Spark SQL syntax unsupported by the Iceberg parser; running a modified Spark whose parser is not the Iceberg ExtendedParser (related IllegalStateException).

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