bazelbuild/bazel · error · OptionsParsingException

Not a valid %s: '%s' (should be %s)

Error message

Not a valid %s: '%s' (should be %s)

What it means

Thrown by EnumConverter.convert when the supplied string does not case-insensitively match any constant of the target enum. The message names the type, echoes the input, and lists the accepted values (the lowercase-joined enum constants) via getTypeDescription().

Source

Thrown at src/main/java/com/google/devtools/common/options/EnumConverter.java:79

            String.format(
                "Enum type %s values %s and %s collide in their case-insensitive string"
                    + " representation '%s'",
                enumType.getName(), enumConstants.get(key).name(), value.name(), key));
      }
      enumConstants.put(key, value);
    }
    return enumType;
  }

  /** Implements {@link Converter#convert(String, Object)}. */
  @Override
  public T convert(String input) throws OptionsParsingException {
    for (T value : enumType.getEnumConstants()) {
      if (Ascii.equalsIgnoreCase(value.toString(), input)) {
        return value;
      }
    }
    throw new OptionsParsingException(
        "Not a valid %s: '%s' (should be %s)".formatted(typeName, input, getTypeDescription()));
  }

  /** Implements {@link #getTypeDescription()}. */
  @Override
  public String getTypeDescription() {
    return Ascii.toLowerCase(
        Converters.joinEnglishList(Arrays.asList(enumType.getEnumConstants())));
  }

  @Override
  public boolean starlarkConvertible() {
    return true;
  }

  @Override
  public String reverseForStarlark(Object converted) {
    checkArgument(enumType.isInstance(converted));

View on GitHub (pinned to e6e199d060)

Solutions

1. Read the '(should be ...)' list in the message and use one of those exact values (case-insensitive).
2. Check the flag's accepted values for your Bazel version: bazel help <command> or the flag's --help output shows the type description.
3. For version-skew, gate the flag in scripts by Bazel version, or upgrade/downgrade Bazel to the version that supports the value.
4. Enable shell completion or validate enum values in wrapper scripts before invoking bazel.

Example fix

# before
bazel build --compilation_mode=fast

# after
bazel build --compilation_mode=fastbuild

// Validate against the actual enum before invoking bazel
Set<String> allowed = Arrays.stream(CompilationMode.values())
    .map(Enum::name).collect(toSet());
if (!allowed.contains(userValue.toUpperCase(Locale.ROOT))) {
  throw new IllegalArgumentException("Value must be one of " + allowed);
}

// Java type guard over the option's enum
static Optional<CompilationMode> asCompilationMode(String s) {
  return Arrays.stream(CompilationMode.values())
      .filter(v -> v.name().equalsIgnoreCase(s)).findFirst();
}

Catch OptionsParsingException and print the '(should be ...)' list from the message to the user verbatim — it is generated from the enum itself and always matches the binary in use.

When it happens

Trigger: Passing an unrecognized value to any enum-typed option, e.g. --compilation_mode=native (valid: fastbuild, dbg, opt), --strategy=blah, or an enum value that only exists in newer Bazel versions. Matching is Ascii.equalsIgnoreCase against value.toString().

Common situations: Version skew: a flag value added in a newer Bazel used against an older binary (or vice versa), typos and abbreviations, using uppercase internally-mapped names that differ from the enum constant spelling, CI pinned to an old Bazel while developers use new flags.

Related errors

• Not one of " + values
• Variable definitions must be in the form of a 'name=value' a
• Must be in the form of a 'key=value[,value]' assignment
• Variable definitions must not contain empty strings or leadi
• Failed to parse CaffeineSpec: " + e.getMessage()

AI-assisted analysis of bazelbuild/bazel@e6e199d060 (2026-08-14). Data as JSON: /api/errors/0d067721a19a064c. Report an issue: GitHub.