What causes "Cannot apply update %s to a view" in apache/iceberg?

Check the update kind before applying: skip or route table-only updates away from ViewMetadata.Builder (e.g. only apply updates whose class implements view support).

apache/iceberg · error · UnsupportedOperationException

Cannot apply update %s to a view

Error message

Cannot apply update %s to a view

What it means

MetadataUpdate.applyTo has two default overloads: one for TableMetadata.Builder and one for ViewMetadata.Builder. Each default throws UnsupportedOperationException for the metadata kind it does not target. Seeing 'Cannot apply update %s to a view' means a table-only update (e.g. AssignUUID, AddSnapshot, SetSnapshotRef) was routed to a view metadata builder because every update type shares this interface and table-specific updates do not override the view overload.

Source

Thrown at core/src/main/java/org/apache/iceberg/MetadataUpdate.java:38

import java.io.Serializable;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import org.apache.iceberg.encryption.EncryptedKey;
import org.apache.iceberg.relocated.com.google.common.collect.ImmutableSet;
import org.apache.iceberg.view.ViewMetadata;
import org.apache.iceberg.view.ViewVersion;

/** Represents a change to table or view metadata. */
public interface MetadataUpdate extends Serializable {
  default void applyTo(TableMetadata.Builder metadataBuilder) {
    throw new UnsupportedOperationException(
        String.format("Cannot apply update %s to a table", this.getClass().getSimpleName()));
  }

  default void applyTo(ViewMetadata.Builder viewMetadataBuilder) {
    throw new UnsupportedOperationException(
        String.format("Cannot apply update %s to a view", this.getClass().getSimpleName()));
  }

  class AssignUUID implements MetadataUpdate {
    private final String uuid;

    public AssignUUID(String uuid) {
      this.uuid = uuid;
    }

    public String uuid() {
      return uuid;
    }

    @Override
    public void applyTo(TableMetadata.Builder metadataBuilder) {
      metadataBuilder.assignUUID(uuid);
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Check the update kind before applying: skip or route table-only updates away from ViewMetadata.Builder (e.g. only apply updates whose class implements view support).
Ensure the update came from the correct entity — do not apply table metadata updates to view metadata.
If you control the code, override applyTo(ViewMetadata.Builder) in custom update types or dispatch via instanceof checks.
Upgrade Iceberg if this occurs with an update type that should support views (newer versions may add view support for more updates).

Example fix

// before
for (MetadataUpdate update : updates) {
  update.applyTo(viewBuilder);
}
// after
for (MetadataUpdate update : updates) {
  if (update instanceof MetadataUpdate.SetProperties
      || update instanceof MetadataUpdate.RemoveProperties) {
    update.applyTo(viewBuilder);
  } // else: table-only update, skip for views
}

Defensive patterns

Strategy: try-catch

Validate before calling

boolean applicableToView = update instanceof MetadataUpdate.SetProperties
    || update instanceof MetadataUpdate.RemoveProperties
    || update instanceof MetadataUpdate.UpgradeFormatVersion;

Type guard

boolean isTableOnly = !(update instanceof MetadataUpdate.SetProperties)
    && !(update instanceof MetadataUpdate.RemoveProperties)
    && !(update instanceof MetadataUpdate.UpgradeFormatVersion);

Try / catch

try {
  update.applyTo(viewMetadataBuilder);
} catch (UnsupportedOperationException e) {
  if (!e.getMessage().contains("to a view")) throw e;
  // skip or reroute table-only update
}

Prevention

Route updates by entity kind before applying; never blindly replay a table's update log onto view metadata.
Maintain a whitelist of update types that apply to views.
Pin client and server Iceberg versions to compatible releases.

When it happens

Trigger: Calling applyTo(ViewMetadata.Builder) on a MetadataUpdate subclass that only overrides applyTo(TableMetadata.Builder), e.g. MetadataUpdate.AssignUUID, AddSnapshot, RemoveSnapshot, SetSnapshotRef, SetSnapshotSummary, UpgradeFormatVersion applied against a view, or a REST client applying an unrecognized/mismatched update fetched from a table's metadata log onto a view.

Common situations: REST catalog clients replaying metadata updates from a table location onto a view object; generic code that iterates a list of MetadataUpdate and applies them without checking whether they are view- or table-applicable; version mismatches where a new table-only update type is applied to views.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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