apache/iceberg · error · IllegalStateException

Cannot load underlying Iceberg view for view: $ident

Error message

Cannot load underlying Iceberg view for view: $ident

What it means

After loading the view metadata through the catalog, the executor must obtain the underlying Iceberg `View` object via `ViewUtil.loadIcebergView`. If that returns empty, the view metadata exists in the catalog but no underlying Iceberg view implementation can be resolved, so an IllegalStateException is thrown rather than committing against a wrong object.

Solutions

1. Confirm the view is actually an Iceberg view (created via the Iceberg catalog)
2. Check catalog configuration so view metadata is registered correctly
3. Re-create the view if metadata is stale or corrupted
4. Check that the correct catalog is named in the identifier

// verify the view resolves through the Iceberg catalog
val catalog = Spark3Util.loadIcebergCatalog(spark, catalogName)
require(catalog.asViewCatalog != null && catalog.loadView(ident) != null, "not an Iceberg view")

try { spark.sql(alterSql) } catch { case e: IllegalStateException if e.getMessage.contains("Cannot load underlying Iceberg view") => /* view is not Iceberg-backed; handle */ }

When it happens

Trigger: Executing `IcebergAlterV2ViewUnsetPropertiesExec` (i.e. `ALTER VIEW ... UNSET TBLPROPERTIES`) when `ViewUtil.loadIcebergView(catalog, ident)` returns `None` — e.g. the catalog entry is not backed by an Iceberg view or cannot be loaded.

Common situations: Pointing the SQL at a non-Iceberg view in a hybrid catalog; catalog/plugin misconfiguration so the view isn't registered as an Iceberg view; stale metadata after concurrent drop/recreate.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple ordering clauses
• ALTER TABLE contains multiple ordering clauses
• ALTER TABLE has no changes: missing both distribution and…

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

Appendix: source

Thrown at spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/execution/datasources/v2/IcebergAlterV2ViewUnsetPropertiesExec.scala:63

  override lazy val output: Seq[Attribute] = Nil

  override protected def run(): Seq[InternalRow] = {
    propertyKeys.foreach(verifyNonReservedPropertyIsUnset)

    val viewInfo = catalog.loadView(ident)
    val properties = viewInfo.properties.asScala.toMap

    if (!ifExists) {
      propertyKeys.filterNot(properties.contains).foreach { property =>
        throw new IcebergAnalysisException(s"Cannot remove property that is not set: '$property'")
      }
    }

    val view =
      ViewUtil
        .loadIcebergView(catalog, ident)
        .getOrElse(
          throw new IllegalStateException(s"Cannot load underlying Iceberg view for view: $ident"))
    val update = view.updateProperties()
    propertyKeys.foreach(update.remove)
    CommandUtils.uncacheTableOrView(session, ResolvedIdentifier(catalog, ident))
    update.commit()

    Nil
  }

  override def simpleString(maxFields: Int): String = {
    s"IcebergAlterV2ViewUnsetProperties: ${ident}"
  }

  private def verifyNonReservedPropertyIsUnset(property: String): Unit = {
    if (SparkView.isReservedProperty(property)) {
      throw new UnsupportedOperationException(s"Cannot unset reserved property: '$property'")
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)