bazelbuild/bazel · error · OptionsParsingException

While parsing option %s: %s

Error message

While parsing option %s: %s

What it means

ParsedOptionDescription.getConvertedValue wraps any OptionsParsingException thrown by the option's Converter during convert(): converters only see the raw string and cannot know which flag they are converting for, so the option's command-line form is prepended to give context. The original converter message (e.g. 'not a boolean', 'not a valid integer', 'not a boolean') is preserved in the wrapped text and cause.

Source

Thrown at src/main/java/com/google/devtools/common/options/ParsedOptionDescription.java:214

  @Nullable
  ParsedOptionDescription getExpandedFrom() {
    return origin.getExpandedFrom();
  }

  public boolean isExplicit() {
    return origin.getExpandedFrom() == null
        && origin.getImplicitDependent() == null
        // Exclude options from PROJECT.scl files, which are not considered explicit.
        && !(origin.getSource() != null && origin.getSource().endsWith("PROJECT.scl"));
  }

  public Object getConvertedValue() throws OptionsParsingException {
    Converter<?> converter = optionDefinition.getConverter();
    try {
      return converter.convert(unconvertedValue, conversionContext);
    } catch (OptionsParsingException e) {
      // The converter doesn't know the option name, so we supply it here by re-throwing:
      throw new OptionsParsingException(
          String.format("While parsing option %s: %s", commandLineForm, e.getMessage()), e);
    }
  }

  @Override
  public String toString() {
    // Check that a dummy value-less option instance does not output all the default information.
    if (commandLineForm == null) {
      return optionDefinition.toString();
    }
    String source = origin.getSource();
    return String.format(
        "option '%s'%s",
        commandLineForm, source == null ? "" : String.format(" (source %s)", source));
  }
}

View on GitHub (pinned to e6e199d060)

Solutions

  1. Read the suffix after the colon — it is the converter's own reason (e.g. 'not a valid integer') and names what the flag actually expects
  2. Check `bazel help <command>` for the flag's expected value format and correct the value
  3. For custom converters in your own options, make the Converter's exception message state the expected format so this wrapper is self-explanatory

Example fix

# before
bazel build --jobs=lots //...
# after
bazel build --jobs=16 //...
Defensive patterns

Strategy: try-catch

Validate before calling

// For custom converters: front-load validation so convert() rarely throws
new Converter<String>() {
  public String convert(String input, Object ctx) throws OptionsParsingException {
    if (!input.matches("[a-z]+")) {
      throw new OptionsParsingException("expected lowercase word, got '" + input + "'");
    }
    return input;
  }
}

Try / catch

Catch OptionsParsingException from getConvertedValue()/parse and parse out the 'While parsing option <form>:' prefix to attribute the failure to the exact flag in user-facing logs.

Prevention

When it happens

Trigger: Any value-conversion failure: `--jobs=abc` (int converter), `--stamp=maybe` (tri-state converter), `--disk_cache=/root/x` (filesystem checks inside converters), invalid regex/enum/path values — every flag whose Converter.convert throws.

Common situations: Wrong value type from CI variables (unquoted empty strings, 'True' vs 'true'); path converters hitting inaccessible directories; enum converters receiving values valid in an older Bazel version.

Related errors

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