apache/iceberg · error · UnsupportedOperationException

Cannot set reserved property: '$property'

Error message

Cannot set reserved property: '$property'

What it means

This UnsupportedOperationException is thrown when a user attempts to SET or UNSET a property on an Iceberg view that is marked as reserved by SparkView.isReservedProperty. Reserved properties are managed internally by Iceberg (e.g. format metadata) and cannot be overwritten through ALTER VIEW SET PROPERTIES.

Solutions

1. Remove the reserved keys from the SET PROPERTIES list and only set user-defined properties
2. Use the documented/allowed view properties; internal metadata is managed automatically
3. Check SparkView.isReservedProperty for the exact list of reserved keys
4. If the internal metadata is genuinely wrong, fix it via catalog-level tooling rather than ALTER VIEW

Example fix

// before
ALTER VIEW iceberg_catalog.db.v SET TBLPROPERTIES ('provider'='iceberg', 'a'='b');
// after: drop the reserved key
ALTER VIEW iceberg_catalog.db.v SET TBLPROPERTIES ('a'='b');

val reserved = Set("provider", "format-version", "format_version") // see SparkView.isReservedProperty
properties.keys.foreach(k => require(!SparkView.isReservedProperty(k), s"$k is a reserved view property"))

def isSettable(k: String): Boolean = !org.apache.iceberg.spark.view.SparkView.isReservedProperty(k)

try { spark.sql("ALTER VIEW ... SET TBLPROPERTIES (...)") } catch {
  case e: UnsupportedOperationException if e.getMessage.contains("reserved property") =>
    logError("remove reserved keys from the property list", e)
}

When it happens

Trigger: Running 'ALTER VIEW ... SET PROPERTIES' or SET TBLPROPERTIES with a key that SparkView classifies as reserved, e.g. internal Iceberg view metadata keys.

Common situations: Copy-pasting table properties (some of which are reserved) onto views; attempting to manually fix internal metadata like provider or format properties; scripts that blanket-set many properties.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot load underlying Iceberg view for view: $ident
• Cannot create view . that references temporary
• Cannot move view between catalogs: from=
• Cannot move view between catalogs: from=
• Cannot remove property that is not set: '$property'

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

Appendix: source

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

      ViewUtil
        .loadIcebergView(catalog, ident)
        .getOrElse(
          throw new IllegalStateException(s"Cannot load underlying Iceberg view for view: $ident"))
    val update = view.updateProperties()
    properties.foreach { case (key, value) => update.set(key, value) }
    CommandUtils.uncacheTableOrView(session, ResolvedIdentifier(catalog, ident))
    update.commit()

    Nil
  }

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

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

View on GitHub (pinned to 86d9c8fc54)