apache/iceberg · error · UnsupportedOperationException

Cannot write manifest list for table version

Error message

Cannot write manifest list for table version: %s

What it means

Thrown when ManifestLists.write is asked to write a manifest list for a table format version that has no registered writer. The switch over formatVersion only covers implemented spec versions; anything else reaches the fall-through UnsupportedOperationException.

Solutions

1. Upgrade the Iceberg library to a version supporting the table's format version.
2. Check TableMetadata.formatVersion() to see which version the table actually uses.
3. Fix code that passes a hardcoded or invalid format-version constant (valid values start at 1).
4. Do not downgrade the client library below the spec version of the table.

Example fix

// before
ManifestLists.write(unsupportedVersion, fileIO, path, spec, ...);
// after
int v = table.operations().current().formatVersion();
if (v > MAX_SUPPORTED_FORMAT_VERSION) {
  throw new IllegalStateException("Upgrade iceberg to write format-version " + v);
}
ManifestLists.write(v, fileIO, path, spec, ...);

int v = table.operations().current().formatVersion();
if (v > SUPPORTED_MAX_FORMAT_VERSION) {
  throw new IllegalStateException("Iceberg build supports up to format-version " + SUPPORTED_MAX_FORMAT_VERSION + ", table is " + v);
}

boolean supportedFormat(int formatVersion) {
  return formatVersion >= 1 && formatVersion <= MAX_SUPPORTED_FORMAT_VERSION;
}

When it happens

Trigger: Calling ManifestLists.write(formatVersion, ...) with a format version not supported by this Iceberg build (e.g., a newer spec version than the library supports, or an invalid value like 0 or a garbage int).

Common situations: A table written by a newer Iceberg/Spark runtime being processed by an older runtime; hand-rolled code passing a wrong version constant; custom catalogs forwarding spec versions from metadata not understood by the current client.

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

• AboveMax has no comparator
• Altering partition keys is not supported yet.
• Altering partition keys is not supported yet.
• Altering schema is not supported in the old alterTable API…
• Avro does not support AAD prefix

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/ManifestLists.java:97

            manifestListFile, encryptionManager, snapshotId, parentSnapshotId, sequenceNumber);
      case 3:
        return new ManifestListWriter.V3Writer(
            manifestListFile,
            encryptionManager,
            snapshotId,
            parentSnapshotId,
            sequenceNumber,
            firstRowId);
      case 4:
        return new ManifestListWriter.V4Writer(
            manifestListFile,
            encryptionManager,
            snapshotId,
            parentSnapshotId,
            sequenceNumber,
            firstRowId);
    }
    throw new UnsupportedOperationException(
        "Cannot write manifest list for table version: " + formatVersion);
  }
}

View on GitHub (pinned to 86d9c8fc54)