apache/iceberg · error · UnsupportedOperationException

does not have a metadata file location

Error message

 does not have a metadata file location

What it means

SerializableTable captures a table's state for serialization (e.g., sending to executors). It only records a metadata file location when built from a table whose TableOperations exposes one. Calling metadataFileLocation() on an instance built without one throws UnsupportedOperationException, since there is no metadata file path to return.

Solutions

  1. Check that the underlying table was loaded from a real catalog entry with a metadata file before serializing
  2. Call metadataFileLocation() only on the original Table, not the SerializableTable wrapper
  3. Re-read the table from its catalog to get a fresh instance with a metadata location

Example fix

// before
SerializableTable st = SerializableTable.of(table);
String loc = st.metadataFileLocation();
// after
String loc = table.operations().current().metadataFileLocation();
Defensive patterns

Strategy: type-guard

Validate before calling

if (table instanceof SerializableTable) { throw new IllegalStateException("Call metadataFileLocation on the live table"); }

Type guard

boolean hasMetadataLocation = !(table instanceof SerializableTable) || table.operations() != null;

Try / catch

try { loc = st.metadataFileLocation(); } catch (UnsupportedOperationException e) { loc = table.operations().current().metadataFileLocation(); }

Prevention

When it happens

Trigger: Calling metadataFileLocation() on a SerializableTable created via SerializableTable.of() from a table whose operations did not provide a metadata file location (e.g., an in-memory/static table without a backing metadata file).

Common situations: Driver-side code inspecting a table after it was serialized for distributed execution; tables loaded via StaticTableOperations with a null metadata location.

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/SerializableTable.java:116

  }

  /**
   * Creates a read-only serializable table that can be sent to other nodes in a cluster.
   *
   * @param table the original table to copy the state from
   * @return a read-only serializable table reflecting the current state of the original table
   */
  public static Table copyOf(Table table) {
    if (table instanceof BaseMetadataTable) {
      return new SerializableMetadataTable((BaseMetadataTable) table);
    } else {
      return new SerializableTable(table);
    }
  }

  public String metadataFileLocation() {
    if (metadataFileLocation == null) {
      throw new UnsupportedOperationException(
          this.getClass().getName() + " does not have a metadata file location");
    }
    return metadataFileLocation;
  }

  private String metadataFileLocation(Table table) {
    if (table instanceof HasTableOperations) {
      TableOperations ops = ((HasTableOperations) table).operations();
      return ops.current().metadataFileLocation();
    } else if (table instanceof BaseMetadataTable) {
      return ((BaseMetadataTable) table).table().operations().current().metadataFileLocation();
    } else {
      return null;
    }
  }

  private Table lazyTable() {
    if (lazyTable == null) {

View on GitHub (pinned to 86d9c8fc54)