apache/iceberg · error · IcebergParseException

${msg}

Error message

${msg}

What it means

This is the IcebergSqlExtensionsErrorStrategy's error handler, which builds and throws an IcebergParseException when the ANTLR-based extended grammar fails to recognize the input. It attaches the source line/position so the message displays the offending SQL fragment.

Solutions

1. Fix the SQL syntax at the reported line/position.
2. Confirm the statement is supported by your Iceberg version's grammar (check IcebergSqlExtensions.g4).
3. Test the statement against a minimal example to isolate the failing clause.
4. Upgrade Iceberg if the syntax is only available in newer releases.

Example fix

// before
spark.sql("ALTER TABLE t WRITE ORDERED B id")
// after
spark.sql("ALTER TABLE t WRITE ORDERED BY id")

// Scala
try { spark.sql(stmt) } catch {
  case e: org.apache.iceberg.spark.sql.IcebergParseException =>
    // e.message contains the SQL snippet and caret; surface it to the user
    throw new IllegalArgumentException(s"Bad Iceberg SQL: ${e.getMessage}", e)
}

When it happens

Trigger: Issuing SQL that matches neither standard Spark grammar nor Iceberg's extensions grammar — e.g. malformed ALTER TABLE ... WRITE DISTRIBUTED/ORDERED BY clauses, bad CALL arguments, or misspelled keywords.

Common situations: Hand-written SQL with typos, SQL generated by scripts with interpolation bugs, migrating statements across Iceberg versions where grammar changed, or forgetting that a feature requires a newer Iceberg release.

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

• ${e.message}
• Invalid transform argument
• msg (syntax error at input position)
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple ordering clauses

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

Appendix: source

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