apache/iceberg · error · java.lang.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 requires the session's current SQL parser to be an Iceberg ExtendedParser (found by unwrapping delegates). If it is not, it throws IllegalStateException 'Cannot parse order: parser is not an Iceberg ExtendedParser', meaning Iceberg's sort-order syntax cannot be handled.

Source

Thrown at spark/v4.2/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. Set spark.sql.extensions to include org.apache.iceberg.spark.extensions.IcebergSparkSqlExtensions
2. If multiple extensions are needed, use a comma-separated list including Iceberg's
3. Verify via SHOW/EXPLAIN or sessionState that the active parser is Iceberg's
4. Upgrade Iceberg if your Spark version wraps parsers in a way findParser cannot unwrap

Example fix

// before
spark.conf.set("spark.sql.extensions", "com.other.MyExtensions")
// after
spark.conf.set("spark.sql.extensions", "com.other.MyExtensions,org.apache.iceberg.spark.extensions.IcebergSparkSqlExtensions")

String ext = spark.conf().get("spark.sql.extensions", "");
if (!ext.contains("org.apache.iceberg.spark.extensions.IcebergSparkSqlExtensions")) {
  throw new IllegalStateException("Enable IcebergSparkSqlExtensions before using ORDERED BY");
}

static boolean hasIcebergParser(SparkSession spark) {
  return ExtendedParser.parseSortOrderAccessible(spark); // or check spark.sessionState().sqlParser()
}

try {
  runOrderedByDdl();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("not an Iceberg ExtendedParser")) {
    log.error("Set spark.sql.extensions to include IcebergSparkSqlExtensions");
  } else throw e;
}

When it happens

Trigger: Running WRITE ORDERED BY / CREATE ... ORDERED BY without the IcebergSparkSqlExtensions enabled, so the session parser is Spark's default rather than the Iceberg ExtendedParser.

Common situations: spark.sql.extensions not configured or overridden by another extensions setting; multiple extensions set without including Iceberg's; parser wrapped so findParser cannot locate it.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot parse order: parser is not an Iceberg ExtendedParser
• Cannot parse order: parser is not an Iceberg ExtendedParser
• Cannot use catalog %s(%s): not a TableCatalog
• Invalid session catalog: sparkSessionCatalog
• Invalid session catalog: ${sparkSessionCatalog}

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