What causes "Invalid status name: %s" in apache/iceberg?

Use the exact enum constant names: see PlanStatus (e.g. SUBMITTED, COMPLETED, FAILED)

apache/iceberg · error · IllegalArgumentException

Invalid status name: %s

Error message

Invalid status name: %s

What it means

PlanStatus.fromName converts a wire/status string into the PlanStatus enum. It uppercases the input and calls valueOf; if the string does not name a valid enum constant, it rethrows IllegalArgumentException with 'Invalid status name'. Null input is rejected separately as 'Status is null'.

Source

Thrown at core/src/main/java/org/apache/iceberg/rest/PlanStatus.java:45

  CANCELLED("cancelled"),
  FAILED("failed");

  private final String status;

  PlanStatus(String status) {
    this.status = status;
  }

  public String status() {
    return status;
  }

  public static PlanStatus fromName(String status) {
    Preconditions.checkArgument(status != null, "Status is null");
    try {
      return PlanStatus.valueOf(status.toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(String.format("Invalid status name: %s", status), e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use the exact enum constant names: see PlanStatus (e.g. SUBMITTED, COMPLETED, FAILED)
Upgrade the client/server so both sides share the same PlanStatus enum values
Trim and check spelling of the status string before parsing
Handle unknown statuses gracefully instead of forwarding raw server strings to fromName

Example fix

// before
PlanStatus s = PlanStatus.fromName(response.status()); // raw server value
// after
String name = response.status() == null ? null : response.status().trim();
PlanStatus s = PlanStatus.fromName(name);

Defensive patterns

Strategy: validation

Validate before calling

boolean isValidStatus(String s) {
  return s != null && java.util.Arrays.stream(PlanStatus.values())
      .anyMatch(v -> v.name().equalsIgnoreCase(s.trim()));
}

Type guard

PlanStatus safeFromName(String s) {
  try { return PlanStatus.fromName(s); } catch (IllegalArgumentException e) { return null; }
}

Try / catch

try {
  status = PlanStatus.fromName(raw);
} catch (IllegalArgumentException e) {
  log.warn("Unknown plan status {}, treating as UNKNOWN", raw, e);
  status = null;
}

Prevention

Only pass exact PlanStatus enum constant names
Trim server-provided status strings before parsing
Keep client and server Iceberg versions aligned
Treat unknown statuses defensively instead of hard-failing

When it happens

Trigger: Parsing a server response containing an unknown status string; passing a lowercase/hyphenated status like 'in-progress' when the enum constant is different; deserializing responses from a newer server whose enum has statuses this client version does not know.

Common situations: REST server and client at different Iceberg versions (new server sends a status the old client lacks); hand-written test fixtures with misspelled status names; case/whitespace issues in config or JSON.

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

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