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

parseSortOrder first locates the session's SQL parser and requires it to be (or unwrap to) an Iceberg ExtendedParser. If the active parser is a plain Spark parser (Iceberg extensions not registered), it throws IllegalStateException because sort-order expressions cannot be parsed without Iceberg's SQL extensions.

Source

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

  1. Configure the session with --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions before running the procedure
  2. If multiple extensions are needed, comma-separate them so Iceberg's is not overwritten: spark.sql.extensions=a.B,c.D,...,org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions
  3. Verify with: SELECT ... — or inspect spark.sessionState.sqlParser; restart the session after fixing config (extensions cannot be reliably applied to an existing session)

Example fix

// before
SparkSession.builder().appName("app").getOrCreate() // no extensions
// after
SparkSession.builder().appName("app")
  .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
  .getOrCreate()
Defensive patterns

Strategy: validation

Validate before calling

// ensure Iceberg extensions are configured before using Iceberg procedures
String ext = spark.conf().get("spark.sql.extensions", "");
if (!ext.contains("IcebergSparkSessionExtensions")) {
  throw new IllegalStateException("Set spark.sql.extensions to include IcebergSparkSessionExtensions");
}

Try / catch

try {
  callRewriteDataFiles(sortOrder);
} catch (IllegalStateException e) {
  if (e.getMessage().contains("parser is not an Iceberg ExtendedParser")) {
    // restart session with spark.sql.extensions configured
  } else { throw e; }
}

Prevention

When it happens

Trigger: Running Iceberg procedures like rewrite_data_files with sort strategy in a SparkSession configured without spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions, or a session where another extension replaced the parser.

Common situations: Notebooks or spark-submit jobs missing the extensions config; using a shared SparkSession initialized by another framework (e.g. Livy, Spark Connect) without Iceberg extensions; conflicting multiple sql.extensions values overwriting Iceberg's.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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