{"record":{"id":"dbb7c0d1b5fbb849","repo":"apache/iceberg","slug":"cannot-set-reserved-property-property","errorCode":null,"errorMessage":"Cannot set reserved property: '$property'","messagePattern":"Cannot set reserved property: '\\$property'","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/execution/datasources/v2/IcebergAlterV2ViewSetPropertiesExec.scala","lineNumber":66,"sourceCode":"      ViewUtil\n        .loadIcebergView(catalog, ident)\n        .getOrElse(\n          throw new IllegalStateException(s\"Cannot load underlying Iceberg view for view: $ident\"))\n    val update = view.updateProperties()\n    properties.foreach { case (key, value) => update.set(key, value) }\n    CommandUtils.uncacheTableOrView(session, ResolvedIdentifier(catalog, ident))\n    update.commit()\n\n    Nil\n  }\n\n  override def simpleString(maxFields: Int): String = {\n    s\"IcebergAlterV2ViewSetProperties: ${ident}\"\n  }\n\n  private def verifyNonReservedPropertyIsSet(property: String): Unit = {\n    if (SparkView.isReservedProperty(property)) {\n      throw new UnsupportedOperationException(s\"Cannot set reserved property: '$property'\")\n    }\n  }\n}\n","sourceCodeStart":48,"sourceCodeEnd":70,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/execution/datasources/v2/IcebergAlterV2ViewSetPropertiesExec.scala#L48-L70","documentation":"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.","triggerScenarios":"Running 'ALTER VIEW ... SET PROPERTIES' or SET TBLPROPERTIES with a key that SparkView classifies as reserved, e.g. internal Iceberg view metadata keys.","commonSituations":"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.","solutions":["Remove the reserved keys from the SET PROPERTIES list and only set user-defined properties","Use the documented/allowed view properties; internal metadata is managed automatically","Check SparkView.isReservedProperty for the exact list of reserved keys","If the internal metadata is genuinely wrong, fix it via catalog-level tooling rather than ALTER VIEW"],"exampleFix":"// before\nALTER VIEW iceberg_catalog.db.v SET TBLPROPERTIES ('provider'='iceberg', 'a'='b');\n// after: drop the reserved key\nALTER VIEW iceberg_catalog.db.v SET TBLPROPERTIES ('a'='b');","handlingStrategy":"validation","validationCode":"val reserved = Set(\"provider\", \"format-version\", \"format_version\") // see SparkView.isReservedProperty\nproperties.keys.foreach(k => require(!SparkView.isReservedProperty(k), s\"$k is a reserved view property\"))","typeGuard":"def isSettable(k: String): Boolean = !org.apache.iceberg.spark.view.SparkView.isReservedProperty(k)","tryCatchPattern":"try { spark.sql(\"ALTER VIEW ... SET TBLPROPERTIES (...)\") } catch {\n  case e: UnsupportedOperationException if e.getMessage.contains(\"reserved property\") =>\n    logError(\"remove reserved keys from the property list\", e)\n}","preventionTips":["Check SparkView.isReservedProperty before including a key","Never hand-edit internal Iceberg view metadata keys","Keep application properties namespaced (e.g. prefix with your app name) to avoid collisions"],"tags":["spark","iceberg","view","properties","reserved"],"backgroundTag":"invalid-config-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}