What causes "this.getClass().getName() + " doesn't implement uuid"" in apache/iceberg?

Only call uuid() on tables backed by real metadata; otherwise read the UUID from table.metadata() or fall back to the table name.

apache/iceberg · error · UnsupportedOperationException

this.getClass().getName() + " doesn't implement uuid"

Error message

this.getClass().getName() + " doesn't implement uuid"

What it means

The default Table.uuid() implementation throws UnsupportedOperationException with the class name appended, because not every Table implementation carries a stable table UUID. Implementations backed by real table metadata (BaseTable) return the metadata's table-uuid; wrappers, metadata tables, and stubs leave the default throwing version.

Source

Thrown at api/src/main/java/org/apache/iceberg/Table.java:372

  /** Returns the current partition statistics files for the table. */
  default List<PartitionStatisticsFile> partitionStatisticsFiles() {
    return ImmutableList.of();
  }

  /**
   * Returns the current refs for the table
   *
   * @return the current refs for the table
   */
  Map<String, SnapshotRef> refs();

  /**
   * Returns the UUID of the table
   *
   * @return the UUID of the table
   */
  default UUID uuid() {
    throw new UnsupportedOperationException(this.getClass().getName() + " doesn't implement uuid");
  }

  /**
   * Returns the snapshot referenced by the given name or null if no such reference exists.
   *
   * @return the snapshot which is referenced by the given name or null if no such reference exists.
   */
  default Snapshot snapshot(String name) {
    SnapshotRef ref = refs().get(name);
    if (ref != null) {
      return snapshot(ref.snapshotId());
    }

    return null;
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Only call uuid() on tables backed by real metadata; otherwise read the UUID from table.metadata() or fall back to the table name.
Catch UnsupportedOperationException and use table.name() or another identity as a fallback key.
Upgrade or unwrap the Table implementation to one that exposes the metadata UUID.
Override uuid() in custom Table implementations to return the metadata table UUID.

Example fix

// before
String id = table.uuid();

// after
String id;
try {
  id = table.uuid();
} catch (UnsupportedOperationException e) {
  id = table.name(); // fallback identity for implementations without UUID
}

Defensive patterns

Strategy: fallback

Validate before calling

// resolve a stable identity without assuming uuid()
String identity;
try { identity = table.uuid(); } catch (UnsupportedOperationException e) { identity = table.name(); }

Type guard

String tableIdOrName(Table t) {
  try { return t.uuid(); }
  catch (UnsupportedOperationException e) { return t.name(); }
}

Try / catch

String id;
try {
  id = table.uuid();
} catch (UnsupportedOperationException e) {
  id = table.name(); // implementations without metadata-backed UUID
}

Prevention

Treat uuid() as an optional capability; always provide a name-based fallback
Avoid persisting table identity keyed solely on uuid() for arbitrary Table implementations
Override uuid() in custom Table implementations backed by TableMetadata

When it happens

Trigger: Calling table.uuid() on a Table that doesn't override uuid() — e.g. SerializableTable delegates, scan-planning paths (planTableScan), metadata-table UUID lookups, or custom Table implementations created in tests (commitToTable, testCompleteCreateTable).

Common situations: Code that identifies tables by UUID across catalogs or serializes table identity; scan planning utilities assuming UUID availability; tests using in-memory table implementations without UUID support.

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/9af0ec9e96a69139. Report an issue: GitHub.