bazelbuild/bazel · error · OptionProcessorException

Option lists a default value (%s) that is not parsable by th

Error message

Option lists a default value (%s) that is not parsable by the option's converter (%s)

What it means

Bazel's options annotation processor validates the defaultValue string of an option by running it through the option's converter at compile time. This error means the converter's convert(defaultValue, null) threw OptionsParsingException — the literal default string cannot be parsed into the option's type.

Source

Thrown at src/main/java/com/google/devtools/common/options/processor/OptionsClassProcessor.java:625

  private void checkForDefaultConverter(
      ExecutableElement method, List<TypeMirror> acceptedConverterReturnTypes, String defaultValue)
      throws OptionProcessorException {
    if (defaultConverters == null) {
      // Bootstrapping. Do not do this check.
      return;
    }

    for (TypeMirror acceptedConverterReturnType : acceptedConverterReturnTypes) {
      Converter<?> converterInstance = findDefaultConverter(acceptedConverterReturnType);
      if (converterInstance == null) {
        continue;
      }
      try {
        converterInstance.convert(defaultValue, null);
      } catch (OptionsParsingException e) {
        TypeElement converter =
            elementUtils.getTypeElement(converterInstance.getClass().getCanonicalName());
        throw new OptionProcessorException(
            method,
            e,
            "Option lists a default value (%s) that is not parsable by the option's converter (%s)",
            defaultValue,
            converter);
      }
      return;
    }
    throw new OptionProcessorException(
        method,
        "Cannot find valid converter for option of type %s",
        acceptedConverterReturnTypes.get(0));
  }

  @Nullable
  private Converter<?> findDefaultConverter(TypeMirror type) {
    // According to the documentation of TypeMirror, equality check is not how one checks whether
    // two instances reference the same type but Types.isSameType().

View on GitHub (pinned to e6e199d060)

Solutions

1. Read the converter named in the message and correct the defaultValue string so the converter accepts it (e.g. "true" not "tru").
2. If the default should be 'unset', use the special defaultValue = "null".
3. If you control the converter, either fix the default string or relax/fix the converter's parsing so the documented default parses.
4. Recompile; the processor re-runs convert() on every build.

Example fix

// before
@Option(
  name = "jobs",
  defaultValue = "auto",
  ...
)
public static int jobs;  // int converter cannot parse "auto"
// after
@Option(
  name = "jobs",
  defaultValue = "0",  // or use a converter/type that accepts "auto"
  ...
)
public static int jobs;

// Verify a default value parses before adding it to the annotation
static <T> String checkDefaultParses(Converter<T> converter, String defaultValue)
    throws OptionsParsingException {
  if (!"null".equals(defaultValue)) {
    converter.convert(defaultValue, null); // throws if unparsable
  }
  return defaultValue;
}

try {
  converter.convert(candidateDefault, null);
} catch (OptionsParsingException e) {
  throw new IllegalArgumentException(
      "defaultValue '" + candidateDefault + "' rejected by " + converter.getClass(), e);
}

When it happens

Trigger: @Option(defaultValue = "...") where the string is malformed for the option's converter — e.g. defaultValue = "tru" for a boolean option, "1.5" for an Integer-typed option, or an unquoted string missing a required prefix/suffix for a custom converter.

Common situations: Typos in default strings; changing an option's type without updating its default; custom converters with strict grammar (e.g. requiring '--flag=value' form or comma-separated lists) where the default was written loosely; note the special string "null" means 'no default' and is typically exempt via converter-specific handling.

Related errors

• Default values for multiple options are not allowed - use "n
• Cannot find valid converter for option of type %s
• The converter type %s must be a concrete type
• Converter %s has %d methods 'convert(String, Object)', expec
• Type of field (%s) must be assignable from the converter's r

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