apache/iceberg · error · UnsupportedOperationException

Cannot load metadata: metadata file location is null

Error message

Cannot load metadata: metadata file location is null

What it means

SerializableTable lazily reconstructs the underlying Table from its serialized metadata file location on first access. If the instance was built without a metadata file location, lazyTable() cannot load anything and throws this UnsupportedOperationException, wrapped as the load failure message.

Source

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

  }

  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) {
      synchronized (this) {
        if (lazyTable == null) {
          if (metadataFileLocation == null) {
            throw new UnsupportedOperationException(
                "Cannot load metadata: metadata file location is null");
          }

          TableOperations ops =
              new StaticTableOperations(metadataFileLocation, io, locationProvider());
          this.lazyTable = newTable(ops, name);
        }
      }
    }

    return lazyTable;
  }

  protected Table newTable(TableOperations ops, String tableName) {
    return new BaseTable(ops, tableName);
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

Serialize the table from a catalog-loaded Table that has a metadata file location
Do not wrap tables lacking a metadata file in SerializableTable for distribution
Re-create the table instance with explicit StaticTableOperations pointing at a valid metadata JSON path

Example fix

// before
SerializableTable.of(inMemoryTable); // no metadata file
// after
Table t = catalog.loadTable(identifier); // has metadata location
SerializableTable.of(t);

Defensive patterns

Strategy: validation

Validate before calling

if (table.operations().current().metadataFileLocation() == null) { throw new IllegalStateException("Table has no metadata file; cannot serialize"); }

Try / catch

try { Table t = serializableTable.newScan().table(); } catch (UnsupportedOperationException e) { /* reload from catalog */ }

Prevention

Only distribute tables loaded from a catalog with persisted metadata
Avoid wrapping StaticTableOperations-based tables with null metadata location
Test serialization round-trips in CI

When it happens

Trigger: Accessing any lazy-delegating method (newScan(), schema(), io() consumers, etc.) on a SerializableTable that was constructed without a metadata file location.

Common situations: A table without a persisted metadata file (e.g., created via newTable on StaticTableOperations with null location) shipped to executors; tasks then fail when they try to touch the table.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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