apache/iceberg · error · UnsupportedOperationException

Replacing a view's version is not supported

Error message

Replacing a view's version is not supported

What it means

View.replaceVersion() is a default interface method that throws UnsupportedOperationException. Creating a ReplaceViewVersion builder is only supported by View implementations that can produce full view metadata updates (e.g. BaseView). Catalog adapters that do not support view version replacement surface this error.

Source

Thrown at api/src/main/java/org/apache/iceberg/view/View.java:104

   */
  default String location() {
    throw new UnsupportedOperationException("Retrieving a view's location is not supported");
  }

  /**
   * Create a new {@link UpdateViewProperties} to update view properties.
   *
   * @return a new {@link UpdateViewProperties}
   */
  UpdateViewProperties updateProperties();

  /**
   * Create a new {@link ReplaceViewVersion} to replace the view's current version.
   *
   * @return a new {@link ReplaceViewVersion}
   */
  default ReplaceViewVersion replaceVersion() {
    throw new UnsupportedOperationException("Replacing a view's version is not supported");
  }

  /**
   * Create a new {@link UpdateLocation} to set the view's location.
   *
   * @return a new {@link UpdateLocation}
   */
  default UpdateLocation updateLocation() {
    throw new UnsupportedOperationException("Updating a view's location is not supported");
  }

  /**
   * Returns the view's UUID
   *
   * @return the view's UUID
   */
  default UUID uuid() {
    throw new UnsupportedOperationException("Retrieving a view's uuid is not supported");

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Load the view from a catalog whose implementation supports replaceVersion() (override it in custom implementations, typically by extending BaseView).
  2. Use engine-level SQL (CREATE OR REPLACE VIEW) instead of the Java ReplaceViewVersion API.
  3. Check the catalog's view-support capabilities before calling replaceVersion().

Example fix

// before
view.replaceVersion()
    .replaceCurrentVersion(sql, "spark", comments, elements)
    .commit();

// after
if (viewSupportsReplaceVersion(view)) {
  view.replaceVersion()
      .replaceCurrentVersion(sql, "spark", comments, elements)
      .commit();
} else {
  catalog.buildReplaceViewVersion(...).createOrReplace().commit();
}
Defensive patterns

Strategy: type-guard

Validate before calling

boolean canReplace = view instanceof BaseView;

Type guard

static boolean supportsReplaceVersion(View v) { return v instanceof BaseView; }

Try / catch

try { view.replaceVersion()...commit(); } catch (UnsupportedOperationException e) { /* use SQL CREATE OR REPLACE VIEW fallback */ }

Prevention

When it happens

Trigger: Calling view.replaceVersion() to build a ReplaceViewVersion operation on a View implementation that has not overridden it.

Common situations: Replacing a view's current SQL version via the catalog API on a catalog whose loaded View lacks replaceVersion support; custom View wrappers in tests.

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/10e13fecf0467e3d. Report an issue: GitHub.