apache/iceberg · error · IcebergParseException

msg (dynamic parse error message)

Error message

msg (dynamic parse error message)

What it means

This is the ANTLR error-listener hook of the Iceberg SQL extensions parser: whenever the lexer/parser fails on Iceberg extension syntax, it throws an IcebergParseException whose message is the dynamic ANTLR parse error and whose Origin marks the failing line and column. It indicates the SQL text does not match the Iceberg extension grammar.

Source

Thrown at spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/parser/extensions/IcebergSparkSqlExtensionsParser.scala:316

case object IcebergParseErrorListener extends BaseErrorListener {
  override def syntaxError(
      recognizer: Recognizer[_, _],
      offendingSymbol: scala.Any,
      line: Int,
      charPositionInLine: Int,
      msg: String,
      e: RecognitionException): Unit = {
    val (start, stop) = offendingSymbol match {
      case token: CommonToken =>
        val start = Origin(Some(line), Some(token.getCharPositionInLine))
        val length = token.getStopIndex - token.getStartIndex + 1
        val stop = Origin(Some(line), Some(token.getCharPositionInLine + length))
        (start, stop)
      case _ =>
        val start = Origin(Some(line), Some(charPositionInLine))
        (start, start)
    }
    throw new IcebergParseException(None, msg, start, stop)
  }
}

/**
 * Copied from Apache Spark
 * A [[ParseException]] is an [[AnalysisException]] that is thrown during the parse process. It
 * contains fields and an extended error message that make reporting and diagnosing errors easier.
 */
class IcebergParseException(
    val command: Option[String],
    message: String,
    val start: Origin,
    val stop: Origin)
    extends AnalysisException(message, start.line, start.startPosition) {

  def this(message: String, ctx: ParserRuleContext) = {
    this(
      Option(IcebergParserUtils.command(ctx)),

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Fix the SQL per the message's line/column and the Iceberg extension grammar (e.g. `ALTER TABLE t WRITE ORDERED BY col`, `CALL catalog.system.procedure(...)`).
2. Verify both parser extensions and the matching iceberg-spark-extensions version are registered for your exact Spark version.
3. Split complex statements and test each clause to isolate the token the parser rejects.
4. If the statement is valid for a newer Iceberg grammar, upgrade the extensions artifact.

Example fix

-- before
ALTER TABLE t WRITE ORDERED BY
-- after
ALTER TABLE t WRITE ORDERED BY col ASC NULLS FIRST

try {
  spark.sql(stmt)
} catch {
  case e: IcebergParseException if e.getMessage.contains("mismatched input") || e.getMessage.contains("no viable alternative") =>
    throw new IllegalArgumentException(s"Check Iceberg SQL syntax near: ${e.getMessage}", e)
}

When it happens

Trigger: Any syntactically invalid use of Iceberg SQL extensions: malformed CALL arguments, wrong ALTER TABLE ... SET TBLPROPERTIES/WRITE DISTRIBUTED/ORDERED BY syntax, unknown branch syntax, or a missing/extra token in an extension statement.

Common situations: Typos in Iceberg-specific clauses; using plain-Spark syntax where the Iceberg grammar requires its own form; forgetting extensions registration so a valid Iceberg statement is parsed by the wrong grammar; version mismatch between grammar features and the Iceberg release.

Understand the failure class

• 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
• msg (syntax error at input position)
• e.message (rethrown as parse error with command context)
• e.message (wrapped as IcebergParseException with command con
• Invalid transform argument

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