apache/iceberg · error · IcebergParseException

${e.message}

Error message

${e.message}

What it means

This is the parser's error-forwarding path: when a statement fails with an IcebergParseException or a Spark AnalysisException during parsing, the parser rethrows it, attaching the original SQL command text so the error message can show a code snippet with a caret pointing at the failing position. It wraps any AnalysisException coming from extended grammar handling into an IcebergParseException with the command attached.

Solutions

1. Read the attached command snippet and caret position to locate the syntax problem and fix the SQL text.
2. Verify org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions is listed in spark.sql.extensions.
3. Check the Iceberg/Spark version pairing; grammar differs between versions.
4. If it is an AnalysisException (not a syntax problem), the table or catalog referenced likely does not exist or is not Iceberg.

Example fix

// before
spark.sql("ALTER TABLE t WRITE ORDERED BY nonexistent_col")
// after
spark.sql("ALTER TABLE t WRITE ORDERED BY id")  // fix column/syntax per the caret in the error

// Scala
try { spark.sql(stmt) } catch {
  case e: org.apache.iceberg.spark.sql.IcebergParseException if e.line.isDefined =>
    log.error(s"Parse failed near line ${e.line.get}: ${e.message}")
}

When it happens

Trigger: Executing any Iceberg-extended SQL statement (ALTER TABLE ... SET TBLPROPERTIES, CALL, ADD PARTITION FIELD, etc.) through SparkSession.sql where the statement fails to parse or a nested AnalysisException is raised during the parse phase.

Common situations: Typos in Iceberg SQL extensions syntax, using a clause unsupported by the configured extensions parser, quoting/escaping mistakes in SQL strings, or running Iceberg SQL on a Spark session that partially registers the extensions.

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

• ${msg}
• 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/a2f2961400bacafc. 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:224

      } 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)