apache/iceberg · error · IcebergParseException

msg (syntax error at input position)

Error message

msg (syntax error at input position)

What it means

The extensions parser's ANTLR error listener converts lexer/parser syntax errors into an IcebergParseException, embedding the original message with the offending line and character position from the token stream. It indicates the SQL text does not conform to Spark grammar plus the Iceberg extension grammar.

Source

Thrown at spark/v3.5/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/parser/extensions/IcebergSparkSqlExtensionsParser.scala:299

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 at the reported line/character position
2. Ensure the Iceberg Spark extensions parser is registered (spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions) and the correct iceberg-spark jar is on the classpath
3. Match the iceberg-spark-runtime artifact version to the exact Spark minor version in use

Example fix

// before
CALL catalog.system.rewrite_datafiles(table => 'db.t', options); // invalid named-arg syntax
// after
CALL catalog.system.rewrite_datafiles(table => 'db.t', options => map('target-file-size-bytes','134217728'));

try {
  spark.sql(sqlText)
} catch {
  case e: IcebergParseException if e.line.isDefined =>
    val l = sqlText.split("\n").apply(e.line.get - 1)
    log.error(s"Syntax error near: $l"); throw e
}

When it happens

Trigger: Submitting SQL that fails ANTLR parsing — unknown tokens, unbalanced parentheses, unsupported Iceberg extension clauses, or using an extension clause with a Spark version whose grammar lacks it.

Common situations: Running Iceberg-specific SQL (CALL, MERGE extensions, ALTER ... WRITE ORDERED BY) against a build missing the extensions parser; typos in SQL; pasting Spark-3.4 syntax into Spark 3.5 clusters without the right jar.

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.

Related errors

• Cannot parse order: parser is not an Iceberg ExtendedParser
• Cannot parse order: parser is not an Iceberg ExtendedParser
• Cannot parse order: parser is not an Iceberg ExtendedParser
• e.message (rethrown as parse error with command context)
• Invalid transform argument

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