{"record":{"id":"fc95226554724b2a","repo":"apache/iceberg","slug":"e-message-wrapped-as-icebergparseexception-with-c","errorCode":null,"errorMessage":"e.message (wrapped as IcebergParseException with command context)","messagePattern":"e\\.message \\(wrapped as IcebergParseException with command context\\)","errorType":"exception","errorClass":"IcebergParseException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/parser/extensions/IcebergSparkSqlExtensionsParser.scala","lineNumber":224,"sourceCode":"      } catch {\n        case _: ParseCancellationException =>\n          // if we fail, parse with LL mode with DefaultErrorStrategy\n          tokenStream.seek(0) // rewind input stream\n          parser.reset()\n\n          // Try Again.\n          parser.setErrorHandler(new DefaultErrorStrategy)\n          parser.getInterpreter.setPredictionMode(PredictionMode.LL)\n          toResult(parser)\n      }\n    } catch {\n      case e: IcebergParseException if e.command.isDefined =>\n        throw e\n      case e: IcebergParseException =>\n        throw e.withCommand(command)\n      case e: AnalysisException =>\n        val position = Origin(e.line, e.startPosition)\n        throw new IcebergParseException(Option(command), e.message, position, position)\n    }\n  }\n\n  override def parseQuery(sqlText: String): LogicalPlan = {\n    parsePlan(sqlText)\n  }\n}\n\nobject IcebergSparkSqlExtensionsParser {\n  private val substitutorCtor: DynConstructors.Ctor[VariableSubstitution] =\n    DynConstructors\n      .builder()\n      .impl(classOf[VariableSubstitution])\n      .impl(classOf[VariableSubstitution], classOf[SQLConf])\n      .build()\n}\n\n/* Copied from Apache Spark's to avoid dependency on Spark Internals */","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/parser/extensions/IcebergSparkSqlExtensionsParser.scala#L206-L242","documentation":"When the Iceberg SQL extension parser hits an AnalysisException during parsing that is not already an IcebergParseException, it wraps the failure in an IcebergParseException carrying the offending SQL command text for better diagnostics. The message shown to the user is the underlying AnalysisException's message, so the real problem is described by the wrapped cause, not by Iceberg itself.","triggerScenarios":"Parsing an Iceberg-extension SQL statement (e.g. CALL, ALTER TABLE ... WRITE ORDERED BY, MERGE branches) whose parse-time resolution fails with a plain Spark AnalysisException; the parser catches it and rethrows with command context attached.","commonSituations":"Syntax accepted by the grammar but referencing something that fails during parsing callbacks (bad multipart identifiers, invalid literals); mixing Spark SQL that only partially matches the Iceberg grammar.","solutions":["Read the wrapped message (the actual AnalysisException text) and fix the underlying SQL problem it describes.","Print/check the command attached to the IcebergParseException to confirm which SQL text failed.","Compare your statement against the Iceberg extension grammar documentation for the exact accepted syntax.","If the SQL is valid but fails due to a parser-side bug, upgrade the iceberg-spark-extensions artifact to match your Spark version."],"exampleFix":"// catch the wrapper and inspect cause\ncatch {\n  case e: IcebergParseException =>\n    log.error(s\"Failed command: ${e.command.getOrElse(\"<unknown>\")}\", e)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  spark.sql(extensionStatement)\n} catch {\n  case e: IcebergParseException =>\n    e.command.foreach(c => log.error(s\"Failing SQL: $c\"))\n    throw new IllegalArgumentException(s\"Bad Iceberg SQL: ${e.getMessage}\", e)\n}","preventionTips":["Validate extension SQL against the Iceberg grammar documentation before shipping scripts","Test DDL scripts against a scratch catalog","Match iceberg-spark-extensions version to your Spark version","Log e.command on failure to see the exact offending statement"],"tags":["spark","sql-parser","exception-wrapping"],"backgroundTag":"invalid-sql-syntax","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}