bazelbuild/bazel · error · OptionsParsingException

Unrecognized option: %s%s

Error message

Unrecognized option: %s%s

What it means

After syntax parsing succeeded, no option definition matched the name (or the matched option is internal and treated as nonexistent). On the final parsing round the parser throws with the offending token plus, for '--' long flags, a SpellChecker 'did you mean' suggestion computed against all valid option names for the command.

Source

Thrown at src/main/java/com/google/devtools/common/options/OptionsParserImpl.java:822

      }
      parsedOptionName = name;
    } else {
      throw new OptionsParsingException("Invalid options syntax: " + arg, arg);
    }

    // Do not recognize internal options, which are treated as if they did not exist.
    if (lookupResult == null || shouldIgnoreOption(lookupResult.definition)) {
      if (isFirstRoundOfParsing) {
        return new ParsedOptionDescriptionOrIgnoredArgs(Optional.empty(), Optional.of(arg));
      }
      String suggestion;
      // Do not offer suggestions for short-form options.
      if (arg.startsWith("--")) {
        suggestion = SpellChecker.didYouMean(arg, getAllValidArgs());
      } else {
        suggestion = "";
      }
      throw new OptionsParsingException("Unrecognized option: " + arg + suggestion, arg);
    }

    if (unconvertedValue == null) {
      // Special-case boolean to supply value based on presence of "no" prefix.
      if (lookupResult.definition.usesBooleanValueSyntax()) {
        unconvertedValue = booleanValue ? "1" : "0";
      } else if (lookupResult.definition.getType().equals(Void.class)) {
        // This is expected, Void type options have no args.
      } else if (nextArgs.hasNext()) {
        // "--flag value" form
        unconvertedValue = nextArgs.next();
        commandLineForm.append(" ").append(unconvertedValue);
      } else {
        throw new OptionsParsingException("Expected value after " + arg);
      }
    }

    if (lookupResult.fromFallback) {

View on GitHub (pinned to e6e199d060)

Solutions

1. Apply the 'Did you mean' suggestion printed in the message if present
2. Run `bazel help <command>` and confirm the flag exists for that command in your Bazel version
3. If the flag comes from .bazelrc, use command-scoped sections (build:..., common:...) or `bazel --ignore_all_rc_files` to bisect which rc line is at fault
4. For renamed flags, migrate to the new name; use Bazel's incompatible-flag migration guides

Example fix

# before
bazel build --compilationMode=fastbuild //...
# after (use snake_case as registered, or the suggestion shown)
bazel build --compilation_mode=fastbuild //...

// Programmatically: confirm a flag exists for the command before building argv
OptionsParser parser = OptionsParser.builder().optionsClasses(...).build();
boolean exists = parser.getOptionsDescription(/* includeDeprecated */)
    .stream().anyMatch(o -> o.getName().equals(flagName));

Catch OptionsParsingException around parse; when the message starts with 'Unrecognized option:', extract the did-you-mean suffix and offer it to the user (or auto-apply it in interactive tooling).

When it happens

Trigger: Passing a flag that does not exist for the current command, a flag gated behind an unreleased/removed Bazel version, a typo'd long flag, or an internal (OptionMetadataTag.INTERNAL) option used externally.

Common situations: Upgrading/downgrading Bazel where a flag was renamed or deleted (e.g. --experimental_* churn); using a command-specific flag on the wrong command (build flag on 'query'); flags defined only when a rule/repository is loaded.

Related errors

• Unexpected value after boolean option: %s
• Malformed value of --invocation_policy:
• Tried to expand option too many times
• Unrecognized arguments:
• Invalid options syntax: %s Note: Negative target patterns ca

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