apache/iceberg · error · IcebergParseException

e.message (rethrown as parse error with command context)

Error message

e.message (rethrown as parse error with command context)

What it means

When parsePlan fails, Iceberg rethrows parse errors, attaching the original SQL command text to the exception so the message includes the offending statement. An IcebergParseException that already has a command is rethrown as-is; one without a command gets withCommand(command) applied; an AnalysisException is converted into an IcebergParseException carrying the line/position origins. The surfaced error message is the underlying parse failure plus command context.

Source

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

      } catch {
        case _: ParseCancellationException =>
          // if we fail, parse with LL mode with DefaultErrorStrategy
          tokenStream.seek(0) // rewind input stream
          parser.reset()

          // Try Again.
          parser.setErrorHandler(new DefaultErrorStrategy)
          parser.getInterpreter.setPredictionMode(PredictionMode.LL)
          toResult(parser)
      }
    } catch {
      case e: IcebergParseException if e.command.isDefined =>
        throw e
      case e: IcebergParseException =>
        throw e.withCommand(command)
      case e: AnalysisException =>
        val position = Origin(e.line, e.startPosition)
        throw new IcebergParseException(Option(command), e.message, position, position)
    }
  }

  override def parseQuery(sqlText: String): LogicalPlan = {
    parsePlan(sqlText)
  }
}

object IcebergSparkSqlExtensionsParser {
  private val substitutorCtor: DynConstructors.Ctor[VariableSubstitution] =
    DynConstructors
      .builder()
      .impl(classOf[VariableSubstitution])
      .impl(classOf[VariableSubstitution], classOf[SQLConf])
      .build()
}

/* Copied from Apache Spark's to avoid dependency on Spark Internals */

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Fix the SQL syntax per the Iceberg DDL docs for your Spark version
2. Read the command context in the message to locate the offending statement and position
3. Verify the Iceberg spark-extensions jar version matches your Spark major version (e.g. spark-extensions for 4.0)

Example fix

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

try { spark.sql(stmt) } catch { case e: IcebergParseException => log.error(s"Failed to parse: ${e.command.getOrElse(stmt)} at line ${e.line}:${e.startPosition}", e) }

When it happens

Trigger: Any invalid Iceberg SQL extension syntax (ALTER TABLE ... TBLPROPERTIES, CALL, etc.) submitted through sql() that fails the Iceberg grammar; also AnalysisExceptions raised during parsing are rewrapped as IcebergParseException.

Common situations: Typo in Iceberg DDL extensions, using Iceberg-specific syntax on a Spark version whose grammar differs, or copy-pasted SQL from docs of a different Iceberg/Spark version.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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)
• msg (syntax error at input position)

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