apache/iceberg · error · UnsupportedOperationException

does not have a format version

Error message

 does not have a format version

What it means

SerializableTable records the table's format version at serialization time. If the version was unknown (UNKNOWN_FORMAT_VERSION, e.g., the source TableOperations did not expose it), formatVersion() throws UnsupportedOperationException naming the concrete class.

Source

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

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

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

  @Override
  public Map<String, String> properties() {
    return properties;
  }

  public int formatVersion() {
    if (formatVersion == UNKNOWN_FORMAT_VERSION) {
      throw new UnsupportedOperationException(
          this.getClass().getName() + " does not have a format version");
    }
    return formatVersion;
  }

  private int formatVersion(Table table) {
    try {
      return TableUtil.formatVersion(table);
    } catch (IllegalArgumentException e) {
      return UNKNOWN_FORMAT_VERSION;
    }
  }

  @Override
  public Schema schema() {
    if (lazySchema == null) {
      synchronized (this) {
        if (lazySchema == null && lazyTable == null) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Read the format version from the underlying TableMetadata before serializing
  2. Ensure the table is loaded from a catalog so its metadata includes the format version
  3. Guard with a check against SerializableTable.UNKNOWN_FORMAT_VERSION-equivalent state before calling
Defensive patterns

Strategy: type-guard

Validate before calling

if (table instanceof SerializableTable) { /* format version may be unknown */ } else { int v = table.operations().current().formatVersion(); }

Type guard

boolean hasFormatVersion = !(table instanceof SerializableTable);

Try / catch

try { v = st.formatVersion(); } catch (UnsupportedOperationException e) { v = MetadataTableUtils...; }

Prevention

When it happens

Trigger: Calling formatVersion() on a SerializableTable that was built from a table whose format version could not be captured (unknown format version sentinel).

Common situations: Reading format version from a table deserialized without version info; custom/in-memory TableOperations implementations not reporting the version.

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