apache/iceberg · error · UnsupportedOperationException

Cannot unset reserved property

Error message

Cannot unset reserved property: '%s' / Cannot set reserved property: '%s' (via errorMsg template)

What it means

verifyNonReservedProperty throws UnsupportedOperationException with either 'Cannot set reserved property: <name>' or 'Cannot unset reserved property: <name>' when a view property change targets a property reserved by SparkView (e.g. 'view-provider', 'identifier', 'location'). Reserved properties control engine behavior and cannot be modified through SET/UNSET TBLPROPERTIES on views.

Solutions

Remove the reserved property key from the SET/UNSET TBLPROPERTIES clause.
Recreate the view with the desired definition/properties if engine metadata must change.
Set only user-level properties not listed in SparkView.RESERVED_PROPERTIES.

Example fix

// before
spark.sql("ALTER VIEW v UNSET TBLPROPERTIES ('provider')") // throws
// after
spark.sql("ALTER VIEW v UNSET TBLPROPERTIES ('my.custom.prop')")

Defensive patterns

Strategy: validation

Validate before calling

import static org.apache.iceberg.spark.SparkView.RESERVED_PROPERTIES;
if (RESERVED_PROPERTIES.contains(propName)) {
  throw new IllegalArgumentException("Property is reserved and cannot be changed: " + propName);
}

Try / catch

try {
  sparkCatalog.alterView(ident, setProperty(k, v));
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("reserved property")) { /* choose a non-reserved key */ }
  throw e;
}

Prevention

Consult SparkView.RESERVED_PROPERTIES before building property updates.
Namespace custom view properties (e.g. 'myapp.prop').
Never SET/UNSET engine-managed keys like provider or identifier.

When it happens

Trigger: ALTER VIEW ... SET TBLPROPERTIES ('provider'='...') or UNSET TBLPROPERTIES on any property in SparkView.RESERVED_PROPERTIES, applied via alterView through SparkCatalog.

Common situations: Users copying table DDL habits (like setting 'provider') to views; migration scripts that unset engine-managed properties; attempting to change view metadata that Iceberg manages internally.

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

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:726

            updateViewProperties.remove(remove.property());
          }
        }

        updateViewProperties.commit();

        return new SparkView(catalogName, view);
      } catch (org.apache.iceberg.exceptions.NoSuchViewException e) {
        throw new NoSuchViewException(ident);
      }
    }

    throw new UnsupportedOperationException(
        "Altering a view is not supported by catalog: " + catalogName);
  }

  private static void verifyNonReservedProperty(String property, String errorMsg) {
    if (SparkView.RESERVED_PROPERTIES.contains(property)) {
      throw new UnsupportedOperationException(String.format(errorMsg, property));
    }
  }

  private static void verifyNonReservedPropertyIsUnset(String property) {
    verifyNonReservedProperty(property, "Cannot unset reserved property: '%s'");
  }

  private static void verifyNonReservedPropertyIsSet(String property) {
    verifyNonReservedProperty(property, "Cannot set reserved property: '%s'");
  }

  @Override
  public boolean dropView(Identifier ident) {
    if (null != asViewCatalog) {
      return asViewCatalog.dropView(buildIdentifier(ident));
    }

    return false;

View on GitHub (pinned to 86d9c8fc54)