apache/iceberg · error · IllegalArgumentException

Unsupported format version:

Error message

Unsupported format version: 

What it means

Default branch of validateDeleteFileForVersion: the producer's format version is outside the handled set (1, 2, 3+). Since the switch only covers 1 and 2 in that branch, any other version value (e.g. a corrupted metadata formatVersion or a forward-compat case not yet implemented) lands here and throws this IllegalArgumentException.

Source

Thrown at core/src/main/java/org/apache/iceberg/MergingSnapshotProducer.java:314

    switch (formatVersion) {
      case 1:
        throw new IllegalArgumentException("Deletes are supported in V2 and above");
      case 2:
        Preconditions.checkArgument(
            file.content() == FileContent.EQUALITY_DELETES || !ContentFileUtil.isDV(file),
            "Must not use DVs for position deletes in V2: %s",
            ContentFileUtil.dvDesc(file));
        break;
      case 3:
      case 4:
        Preconditions.checkArgument(
            file.content() == FileContent.EQUALITY_DELETES || ContentFileUtil.isDV(file),
            "Must use DVs for position deletes in V%s: %s",
            formatVersion,
            file.location());
        break;
      default:
        throw new IllegalArgumentException("Unsupported format version: " + formatVersion);
    }
  }

  private int formatVersion() {
    return ops().current().formatVersion();
  }

  /** Add all files in a manifest to the new snapshot. */
  protected void add(ManifestFile manifest) {
    Preconditions.checkArgument(
        manifest.content() == ManifestContent.DATA, "Cannot append delete manifest: %s", manifest);
    if (canInheritSnapshotId() && manifest.snapshotId() == null) {
      Preconditions.checkArgument(
          manifest.firstRowId() == null,
          "Cannot append manifest with assigned first_row_id: %s",
          manifest.firstRowId());
      appendedManifestsSummary.addedManifest(manifest);
      appendManifests.add(manifest);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg client/engine to a version supporting the table's format version
2. Check the table metadata's 'format-version' field for corruption or unexpected values
3. Recreate or migrate the table to a supported format version
4. Do not manually edit metadata files

Example fix

// before: old client reading newer table
// iceberg-spark 3.3 with format-version=3 table
// after: align client with table format version
// upgrade to a release supporting format-version 3, or set 'format-version'='2' when writing the table

int v = table.ops().current().formatVersion();
if (v != 1 && v != 2 && v != 3) throw new IllegalStateException("Unsupported table format version: " + v + "; upgrade the Iceberg client");

try { rowDelta.commit(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unsupported format version")) { /* upgrade client or migrate table */ } throw e; }

When it happens

Trigger: formatVersion() returns a value not covered by the switch (e.g. metadata formatVersion >= 4 not yet supported, or corrupted TableMetadata formatVersion) while validating delete files.

Common situations: Running an older Iceberg client against a table written by a newer writer with a higher format version; hand-edited/corrupted metadata JSON.

Related errors

• Deletes are supported in V2 and above
• Invalid distribution mode: %s
• Unsorted order ID must be 0
• Sort order ID 0 is reserved for unsorted order
• Visitor %s does not support non-reference: %s

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