apache/iceberg · error · IcebergParseException

msg (syntax error at input position)

Error message

msg (syntax error at input position)

What it means

This is the Iceberg extension parser's syntax-error path: when the ANTLR lexer/parser fails, it builds start/stop Origin positions from the failing token and throws IcebergParseException with the generated message describing the syntax error and where it occurred. It means the SQL did not match the Iceberg-extended Spark grammar.

Solutions

1. Check the reported line/column in the message and correct the syntax
2. Confirm iceberg-spark-extensions jar is on the classpath and registered via spark.sql.extensions
3. Compare the statement against Iceberg docs examples for your version

Example fix

// before
spark.sql("ALTER TABLE t WRITE HASH BY id") // syntax error
// after
spark.sql("ALTER TABLE t WRITE DISTRIBUTED BY HASH ORDERED BY id")

def isKnownIcebergDdl(stmt: String): Boolean = stmt.trim.toUpperCase(Locale.ROOT).matches("(ALTER TABLE|CALL|ALTER VIEW).*")

try { spark.sql(stmt) } catch { case e: IcebergParseException => println(s"Syntax error near line ${e.line}, col ${e.startPosition}: ${e.getMessage}") }

When it happens

Trigger: Submitting SQL containing Iceberg extension syntax that does not parse: malformed ALTER TABLE write spec, CALL arguments, identifier issues, or any token the extended grammar cannot accept.

Common situations: Typos, missing keywords (e.g. forgot ORDERED BY), mixing Spark 3 syntax with Spark 4 extensions, unbalanced parentheses, or Iceberg extension jars missing so base Spark grammar rejects Iceberg keywords.

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}
• e.message (rethrown as parse error with command context)

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

Appendix: source

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

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)