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 plan parsing fails, this catch block rethrows the underlying error: IcebergParseErrors keep their original command context, other IcebergParseExceptions get the current command attached, and plain AnalysisExceptions are converted into an IcebergParseException carrying the SQL command and error position. It surfaces the underlying e.message enriched with the command being parsed.

Source

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

      } 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

Fix the SQL syntax or semantic issue reported in e.message — the error reflects a real problem in the parsed statement
Verify Spark and Iceberg versions are compatible (grammar files must match the Spark minor version)
Run the failing statement through the appropriate Iceberg grammar docs to confirm supported syntax

Example fix

// before (ambiguous/unsupported syntax)
ALTER TABLE t WRITE ORDERED BY;
// after
ALTER TABLE t WRITE ORDERED BY id;

Defensive patterns

Strategy: try-catch

Try / catch

try {
  parser.parsePlan(sqlText)
} catch {
  case e: IcebergParseException =>
    log.error(s"Failed parsing command: ${e.getMessage}"); throw e
}

Prevention

Validate SQL against the Iceberg extension grammar before submitting
Keep Spark and Iceberg extension jars version-aligned
Log the full command text when parse errors occur

When it happens

Trigger: Calling parsePlan/parseQuery with SQL that triggers an analysis or Iceberg parse failure inside the extensions parser — e.g. malformed MERGE/ALTER statements or expressions failing analysis mid-parse.

Common situations: Submitting invalid Iceberg SQL extensions syntax through Spark; mismatched grammar between Spark and Iceberg extension versions.

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

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