apache/iceberg · warning · IllegalArgumentException

Unknown delete granularity:

Error message

Unknown delete granularity: 

What it means

DeleteGranularity.toString() converts the enum constant to its lowercase string form ("file" or "partition") and throws IllegalArgumentException in the default branch. This can only fire if a new enum constant was added without updating toString, or the default case is reached in a switch over the enum.

Solutions

1. Add a case for the missing enum constant in the toString switch.
2. Use only the released constants FILE and PARTITION.
3. Report an internal invariant violation upstream if encountered with an unmodified release.

Example fix

// before
case PARTITION: return "partition";
default: throw new IllegalArgumentException(...);
// after
case PARTITION: return "partition";
case ROW: return "row"; // new constant handled
default: throw new IllegalArgumentException(...);

null

if (g == DeleteGranularity.FILE || g == DeleteGranularity.PARTITION) { /* safe to use g.toString() */ }

try { return granularity.toString(); } catch (IllegalArgumentException e) { return granularity.name().toLowerCase(Locale.ROOT); }

When it happens

Trigger: Internally: a DeleteGranularity enum constant lacking a case in the toString switch. Practically unreachable for users of the released enum with only FILE and PARTITION.

Common situations: Custom patched builds adding a new granularity without updating toString; internal invariant violation during configuration rendering or metadata serialization.

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

• Cannot apply unknown unique constraint:
• Cannot apply unknown unique constraint:
• Cannot call commit on temporary table operations
• Cannot call refresh on temporary table operations
• Cannot copy

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

Appendix: source

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

 * <p>Currently, this configuration is only applicable to position deletes.
 *
 * <p>Each granularity has its own benefits and drawbacks and should be picked based on a use case.
 * Regular delete compaction is still required regardless of which granularity is chosen. It is also
 * possible to use one granularity for ingestion and another one for table maintenance.
 */
public enum DeleteGranularity {
  FILE,
  PARTITION;

  @Override
  public String toString() {
    switch (this) {
      case FILE:
        return "file";
      case PARTITION:
        return "partition";
      default:
        throw new IllegalArgumentException("Unknown delete granularity: " + this);
    }
  }

  public static DeleteGranularity fromString(String valueAsString) {
    Preconditions.checkArgument(valueAsString != null, "Value is null");
    if (FILE.toString().equalsIgnoreCase(valueAsString)) {
      return FILE;
    } else if (PARTITION.toString().equalsIgnoreCase(valueAsString)) {
      return PARTITION;
    } else {
      throw new IllegalArgumentException("Unknown delete granularity: " + valueAsString);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)