apache/iceberg · error · IllegalArgumentException

Deletes are supported in V2 and above

Error message

Deletes are supported in V2 and above

What it means

Thrown by MergingSnapshotProducer.validateDeleteFileForVersion when a delete file is being added to (or validated against) a table whose format version is 1. Delete files (position and equality deletes) were introduced in format version 2, so any attempt to commit deletes to a v1 table fails fast with this IllegalArgumentException.

Source

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

    if (ContentFileUtil.isDV(file)) {
      List<DeleteFile> dvsForReferencedFile =
          dvsByReferencedFile.computeIfAbsent(
              file.referencedDataFile(), newFile -> Lists.newArrayList());
      dvsForReferencedFile.add(file);
    } else {
      v2Deletes.add(file);
    }
  }

  protected void validateNewDeleteFile(DeleteFile file) {
    Preconditions.checkNotNull(file, "Invalid delete file: null");
    validateDeleteFileForVersion(file, formatVersion());
  }

  private static void validateDeleteFileForVersion(DeleteFile file, int formatVersion) {
    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);
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the table: UPDATE the table format version (table.updateProperties or rewrite with table property 'format-version'='2' at creation) and re-run the operation
2. Create new tables with format-version=2 or 3 if delete support is needed
3. Remove the delete-file path from the v1 table operation (use rewrite/overwrite instead of deletes)
4. Check Spark/Engine table creation properties ensuring format-version>=2

Example fix

// before: v1 table cannot take deletes
table.newRowDelta().addDeletes(deleteFile).commit();
// after: set format version before creating the table
Map<String,String> props = Map.of(TableProperties.FORMAT_VERSION, "2");
tables.create(schema, PartitionSpec.unpartitioned(), props, "s3://bucket/table");

boolean deletesSupported = table.ops().current().formatVersion() >= 2;
if (!deletesSupported) throw new IllegalStateException("Upgrade table to format-version >= 2 before committing delete files");

try { rowDelta.commit(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("V2 and above")) { /* migrate table or use rewrite instead */ } throw e; }

When it happens

Trigger: Calling newRowDelta() or newOverwrite() with a DeleteFile on a table with formatVersion=1; also triggered by validateDeleteFilesForVersion when inherited/delete files exist on a v1 table.

Common situations: Adding deletes to old pre-v2 tables that were never upgraded; cluster/tooling that defaults new tables to formatVersion 1; copy/migrate jobs that pass delete files from a v2 table to a v1 table.

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

• Cannot write delete files in a v1 table
• Unsupported format version:
• Found conflicting files that can contain records matching %s
• Unknown delete file content:
• Invalid distribution mode: %s

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