apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot retrieve UUID for table <table.name()>

Error message

Cannot retrieve UUID for table <table.name()>

What it means

uuid() helper returns a table's metadata UUID, but only when the Table implements HasTableOperations or is a BaseMetadataTable. Any other Table implementation has no accessible operations/metadata, so this UnsupportedOperationException is thrown.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:1034

    Preconditions.checkArgument(
        namespace.length <= 1,
        "Cannot convert %s to a Spark v1 identifier, namespace contains more than 1 part",
        identifier);

    String table = identifier.name();
    Option<String> database = namespace.length == 1 ? Option.apply(namespace[0]) : Option.empty();
    return org.apache.spark.sql.catalyst.TableIdentifier.apply(table, database);
  }

  public static String baseTableUUID(org.apache.iceberg.Table table) {
    if (table instanceof HasTableOperations) {
      TableOperations ops = ((HasTableOperations) table).operations();
      return ops.current().uuid();
    } else if (table instanceof BaseMetadataTable) {
      return ((BaseMetadataTable) table).table().operations().current().uuid();
    } else {
      throw new UnsupportedOperationException("Cannot retrieve UUID for table " + table.name());
    }
  }

  private static class DescribeSortOrderVisitor implements SortOrderVisitor<String> {
    private static final DescribeSortOrderVisitor INSTANCE = new DescribeSortOrderVisitor();

    private DescribeSortOrderVisitor() {}

    @Override
    public String field(
        String sourceName,
        int sourceId,
        org.apache.iceberg.SortDirection direction,
        NullOrder nullOrder) {
      return String.format("%s %s %s", sourceName, direction, nullOrder);
    }

    @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Obtain a BaseTable or HasTableOperations instance from the Iceberg catalog rather than a generic wrapper.
2. Unwrap the table (e.g. ((SparkTable) t).table()) before requesting the UUID.
3. For metadata tables (e.g. db.table.refs), use the table() accessor path handled by BaseMetadataTable.
4. Guard with instanceof checks and skip/report tables lacking operations instead of crashing.

Example fix

// before
Table t = someWrapperTable();
String uuid = Spark3Util.uuid(t); // throws
// after
if (t instanceof BaseTable) {
  String uuid = Spark3Util.uuid(((BaseTable) t).table());
}

// Java
boolean canGetUuid = table instanceof HasTableOperations
    || table instanceof BaseMetadataTable
    || (table instanceof BaseTable);

String safeUuid(Table table) {
  if (table instanceof HasTableOperations) {
    return ((HasTableOperations) table).operations().current().uuid();
  } else if (table instanceof BaseMetadataTable) {
    return ((BaseMetadataTable) table).table().operations().current().uuid();
  }
  return null; // caller decides fallback
}

try {
  uuid = Spark3Util.uuid(table);
} catch (UnsupportedOperationException e) {
  uuid = null; // skip uuid-dependent reporting for this table
}

When it happens

Trigger: Calling Spark3Util.uuid(table) with a Table wrapper that is neither HasTableOperations nor a BaseMetadataTable — e.g. custom Table implementations, mocked tables, or SparkTable delegates exposing unsupported inner tables.

Common situations: Building tools/metrics over tables from catalogs that return wrapped or lazy Table objects; using tables obtained through third-party catalog adapters instead of Iceberg's BaseTable.

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

• Renaming a view is not supported by catalog: ${catalogName}
• Cannot convert predicate to SQL: <pred>
• Cannot convert term to SQL: <term>
• Unsupported task group for row-based reads: ${partition.task
• Columnar reads are not supported

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