apache/iceberg · error · IllegalArgumentException

String.format("Invalid mode: %s", modeAsString)

Error message

String.format("Invalid mode: %s", modeAsString)

What it means

PrefixMismatchMode.fromString parses a string into the PrefixMismatchMode enum via valueOf after upper-casing; any string that is not exactly one of the enum constants (case-insensitively) throws IllegalArgumentException with "Invalid mode: <value>", chaining the original exception. A null input fails first with "Invalid mode: null".

Source

Thrown at api/src/main/java/org/apache/iceberg/actions/DeleteOrphanFiles.java:168

  }

  /**
   * Defines the action behavior when location prefixes (scheme/authority) mismatch.
   *
   * <p>{@link #ERROR} - throw an exception. {@link #IGNORE} - no action. {@link #DELETE} - delete
   * files.
   */
  enum PrefixMismatchMode {
    ERROR,
    IGNORE,
    DELETE;

    public static PrefixMismatchMode fromString(String modeAsString) {
      Preconditions.checkArgument(modeAsString != null, "Invalid mode: null");
      try {
        return PrefixMismatchMode.valueOf(modeAsString.toUpperCase(Locale.ROOT));
      } catch (IllegalArgumentException e) {
        throw new IllegalArgumentException(String.format("Invalid mode: %s", modeAsString), e);
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Pass one of the exact enum constant names: ERROR, REMOVE, or NONE (case-insensitive).
  2. Trim and normalize the input string before calling fromString.
  3. Handle null explicitly by choosing a default mode instead of passing null.

Example fix

// before
PrefixMismatchMode mode = PrefixMismatchMode.fromString(config.get("mode")); // "delete" -> throws
// after
String raw = Optional.ofNullable(config.get("mode")).map(String::trim).orElse("NONE");
PrefixMismatchMode mode = PrefixMismatchMode.fromString(raw);
Defensive patterns

Strategy: validation

Validate before calling

String raw = mode == null ? null : mode.trim();
boolean valid = raw != null && Arrays.stream(PrefixMismatchMode.values())
    .anyMatch(m -> m.name().equalsIgnoreCase(raw));

Type guard

if (modeAsString == null || modeAsString.isBlank()) { modeAsString = "NONE"; }

Try / catch

try { mode = PrefixMismatchMode.fromString(raw); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Unknown prefixMismatchMode '" + raw + "'; expected ERROR, REMOVE or NONE", e); }

Prevention

When it happens

Trigger: Calling PrefixMismatchMode.fromString with a misspelled or unknown mode string, e.g. "delete", "error", "none " (whitespace), or an empty string, when configuring DeleteOrphanFiles prefix mismatch handling.

Common situations: Mode name read from a config file/property that doesn't match an enum constant (e.g., lowercase typos, aliases like "fail" instead of "ERROR"); null values propagating from unset configuration.

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/b9a6e2ffba9b705f. Report an issue: GitHub.