apache/iceberg · error · UnsupportedOperationException

Cannot unset reserved property: '$property'

Error message

Cannot unset reserved property: '$property'

What it means

Iceberg reserves certain view property keys for internal bookkeeping (metadata location, provider, etc.). Unsetting them through `ALTER VIEW ... UNSET TBLPROPERTIES` would corrupt view metadata, so the executor rejects reserved keys with an UnsupportedOperationException via `SparkView.isReservedProperty`.

Solutions

1. Remove reserved keys from the UNSET list
2. Only unset properties shown as user-defined in `SHOW TBLPROPERTIES`
3. If the intent is to replace the view, use CREATE OR REPLACE instead of unsetting internal properties

Example fix

// before
ALTER VIEW v UNSET TBLPROPERTIES ('provider', 'x.y')
// after
ALTER VIEW v UNSET TBLPROPERTIES ('x.y') -- drop only user-defined properties

val reserved = Set("location","provider","format-provider","metadata.previous-location","metadata.current-location")
require((keysToUnset & reserved).isEmpty, s"reserved keys: ${(keysToUnset & reserved).mkString(",")}")

try { spark.sql(unsetSql) } catch { case e: UnsupportedOperationException if e.getMessage.contains("reserved property") => /* filter out reserved keys and retry */ }

When it happens

Trigger: Calling `verifyNonReservedPropertyIsUnset` with a key that `SparkView.isReservedProperty` returns true for, typically via `ALTER VIEW ... UNSET TBLPROPERTIES ('provider', ...)` or similar reserved keys.

Common situations: Scripts that blindly unset a list of properties including reserved ones; attempts to 'clean up' properties that look user-defined but are internal; migrating views and resetting all properties.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot remove property that is not set: '$property'
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple ordering clauses
• ALTER TABLE contains multiple ordering clauses

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/7a1f2d7645ec8666. 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:78

      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)