apache/iceberg · error · UnsupportedOperationException

does not support purging tables

Error message

 does not support purging tables

What it means

This UnsupportedOperationException is a deliberate guard in SparkCachedTableCatalog.purgeTable: purging means deleting a table plus all of its data/metadata files, which is a destructive operation on the backing Iceberg table that a cache-only catalog does not perform. Any DROP TABLE ... PURGE (or catalog purgeTable call) routed here hits this unconditional sentinel instead of touching storage.

Solutions

  1. Purge the table via the real Iceberg catalog
  2. Exclude cached-catalog tables from purge tooling
  3. Use expire_snapshots / purge procedures against the owning catalog instead
Defensive patterns

Strategy: validation

Validate before calling

if (catalog instanceof SparkCachedTableCatalog) {
  throw new IllegalArgumentException("PURGE not supported on cached catalog; use owning catalog");
}

Try / catch

try { catalog.purgeTable(ident); } catch (UnsupportedOperationException e) { realCatalog.purgeTable(ident); }

Prevention

When it happens

Trigger: Running DROP TABLE ... PURGE (or an engine call to purgeTable) on a table resolved via the cached-table catalog.

Common situations: Lifecycle-management jobs issuing PURGE against every table in a namespace, hitting this passthrough catalog.

Related errors

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCachedTableCatalog.java:113

  public SparkTable createTable(
      Identifier ident, StructType schema, Transform[] partitions, Map<String, String> properties)
      throws TableAlreadyExistsException {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support creating tables");
  }

  @Override
  public SparkTable alterTable(Identifier ident, TableChange... changes) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support altering tables");
  }

  @Override
  public boolean dropTable(Identifier ident) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support dropping tables");
  }

  @Override
  public boolean purgeTable(Identifier ident) throws UnsupportedOperationException {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support purging tables");
  }

  @Override
  public void renameTable(Identifier oldIdent, Identifier newIdent) {
    throw new UnsupportedOperationException(CLASS_NAME + " does not support renaming tables");
  }

  @Override
  public void initialize(String catalogName, CaseInsensitiveStringMap options) {
    this.name = catalogName;
  }

  @Override
  public String name() {
    return name;
  }

  private SparkTable load(Identifier ident) throws NoSuchTableException {

View on GitHub (pinned to 86d9c8fc54)