apache/iceberg · error · IllegalArgumentException

Unknown row-level operation mode:

Error message

Unknown row-level operation mode: 

What it means

RowLevelOperationMode.fromName throws IllegalArgumentException when the given mode name string matches neither 'copy-on-write' nor 'merge-on-read' (case-insensitive). It parses the write.merge.mode / delete mode table property value.

Source

Thrown at core/src/main/java/org/apache/iceberg/RowLevelOperationMode.java:57

 */
public enum RowLevelOperationMode {
  COPY_ON_WRITE("copy-on-write"),
  MERGE_ON_READ("merge-on-read");

  private final String modeName;

  RowLevelOperationMode(String modeName) {
    this.modeName = modeName;
  }

  public static RowLevelOperationMode fromName(String modeName) {
    Preconditions.checkArgument(modeName != null, "Mode name is null");
    if (COPY_ON_WRITE.modeName().equalsIgnoreCase(modeName)) {
      return COPY_ON_WRITE;
    } else if (MERGE_ON_READ.modeName().equalsIgnoreCase(modeName)) {
      return MERGE_ON_READ;
    } else {
      throw new IllegalArgumentException("Unknown row-level operation mode: " + modeName);
    }
  }

  public String modeName() {
    return modeName;
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set the mode property to exactly 'copy-on-write' or 'merge-on-read'.
2. Check the configured value with SQL: SHOW TBLPROPERTIES / DESCRIBE TABLE, and fix the typo.
3. Upgrade Iceberg if a newer mode value from documentation is not recognized.

Example fix

// before
ALTER TABLE t SET TBLPROPERTIES ('write.merge.mode'='MOR');
// after
ALTER TABLE t SET TBLPROPERTIES ('write.merge.mode'='merge-on-read');

String mode = table.properties().getOrDefault(TableProperties.MERGE_MODE, "copy-on-write");
if (!"copy-on-write".equalsIgnoreCase(mode) && !"merge-on-read".equalsIgnoreCase(mode)) {
  throw new IllegalArgumentException("invalid write.merge.mode: " + mode);
}

try { RowLevelOperationMode.fromName(modeName); } catch (IllegalArgumentException e) { /* fall back to COPY_ON_WRITE */ }

When it happens

Trigger: Setting table property write.merge.mode (or spark.merge-on-read related mode configs) to an unrecognized string, then starting a COPY ON WRITE / MERGE ON WRITE operation that calls RowLevelOperationMode.fromName.

Common situations: Typos like 'copy_on_write', 'COW', 'mergeOnRead'; copying a mode value from another engine's config; version drift where a newer mode name is used on an older Iceberg.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid rewrite job order name: %s
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}
• String.format("Invalid snapshot ref type: %s", snapshotRefTy
• Unsupported file content type: ${file.content()}

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