apache/iceberg · error · IllegalStateException

Cannot parse order: parser is not an Iceberg ExtendedParser

Error message

Cannot parse order: parser is not an Iceberg ExtendedParser

What it means

When Spark session's SQL parser is not (wrapping) Iceberg's ExtendedParser, parseSortOrder cannot parse order strings and throws IllegalStateException('Cannot parse order: parser is not an Iceberg ExtendedParser'). ExtendedParser is contributed by the Iceberg Spark extensions, so this indicates the extensions/parser plugin isn't active in the session.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/ExtendedParser.java:67

      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);
    }

    return null;
  }

  private static ParserInterface getNextDelegateParser(ParserInterface parser) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Set spark.sql.extensions=org.apache.iceberg.spark.SparkSessionExtensions in the Spark config and include the iceberg-spark runtime jar on the classpath.
Check spark.sql.catalog.<name> points at the Iceberg catalog and extensions are applied to the correct session.
If a third-party parser plugin is installed, ensure it wraps or falls through to Iceberg's ExtendedParser (findParser walks the delegation chain).
Alternatively compute sort orders via the Iceberg Java API (SortOrder.builderFor(schema)...) instead of string parsing.

Example fix

// before
spark = SparkSession.builder().appName("job").getOrCreate(); // no Iceberg extensions
// after
spark = SparkSession.builder()
    .appName("job")
    .config("spark.sql.extensions", "org.apache.iceberg.spark.SparkSessionExtensions")
    .getOrCreate();

Defensive patterns

Strategy: validation

Validate before calling

boolean ok = spark.conf().get("spark.sql.extensions", "")
    .contains("org.apache.iceberg.spark.SparkSessionExtensions");
if (!ok) throw new IllegalStateException("Iceberg Spark extensions not configured");

Try / catch

try { parseSortOrder(spark, orderString); } catch (IllegalStateException e) { throw new ConfigException("Enable Iceberg SparkSessionExtensions to parse sort orders", e); }

Prevention

Always set spark.sql.extensions to include SparkSessionExtensions when using Iceberg SQL features
Keep the iceberg-spark runtime jar on the driver and executor classpath
Avoid third-party parser plugins that bypass the Iceberg ExtendedParser chain

When it happens

Trigger: Calling parseSortOrder (or SQL like ALTER TABLE ... WRITE ORDERED BY) in a SparkSession where the Iceberg SparkSessionExtensions were never injected, or a custom ParserInterface replaced the default without extending ExtendedParser.

Common situations: Missing .config('spark.sql.extensions', 'org.apache.iceberg.spark.SparkSessionExtensions'); spark-sql without the iceberg runtime jar configured; another catalog/parser extension overriding the SQL parser chain.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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