bazelbuild/bazel · error · OptionsParsingException

Unrecognized arguments:

Error message

Unrecognized arguments: 

What it means

OptionsParserImpl.addResidueFromResult throws when parsing produced leftover non-option arguments (residue) but the parser was configured with allowResidue=false. Residue means tokens that are neither recognized options nor consumed as option values; commands that expect only flags reject them with this error listing every leftover token.

Source

Thrown at src/main/java/com/google/devtools/common/options/OptionsParser.java:717

    Preconditions.checkNotNull(
        optionToExpand, "Option for expansion not specified for arglist %s", args);
    Preconditions.checkArgument(
        optionToExpand.getPriority().getPriorityCategory()
            != OptionPriority.PriorityCategory.DEFAULT,
        "Priority cannot be default, which was specified for arglist %s",
        args);
    OptionsParserImplResult optionsParserImplResult =
        impl.parseArgsAsExpansionOfOption(optionToExpand, o -> source, args);
    addResidueFromResult(optionsParserImplResult);
    return optionsParserImplResult.ignoredArgs;
  }

  private void addResidueFromResult(OptionsParserImplResult result) throws OptionsParsingException {
    residue.addAll(result.getResidue());
    postDoubleDashResidue.addAll(result.postDoubleDashResidue);
    if (!allowResidue && !residue.isEmpty()) {
      String errorMsg = "Unrecognized arguments: " + Joiner.on(' ').join(residue);
      throw new OptionsParsingException(errorMsg);
    }
  }

  /**
   * Sets provided value for a flag with a particular priority. This only sets the value of the flag
   * itself and does not affect any of its implicit requirements or expansions.
   *
   * @param origin the origin of this option instance, it includes the priority of the value. If
   *     other values have already been or will be parsed at a higher priority, they might override
   *     the provided value. If this option already has a value at this priority, this value will
   *     have precedence, but this should be avoided, as it breaks order tracking.
   * @param option the option to add the value for.
   * @param value the value to add at the given priority.
   */
  void setOptionValueAtSpecificPriorityWithoutExpansion(
      OptionInstanceOrigin origin, OptionDefinition option, String value)
      throws OptionsParsingException {
    impl.setOptionValueAtSpecificPriorityWithoutExpansion(origin, option, value);

View on GitHub (pinned to e6e199d060)

Solutions

1. Remove the non-option arguments from the command line; move target patterns after '--' only if the command actually accepts them
2. Check for a misspelled or unavailable flag — unknown flags on residue-free commands surface this way; run with --help to list valid flags
3. If you are the command author and targets are legitimate, set allowResidue() to true in your OptionsModule/OptionsBase spec

Example fix

# before
bazel help --scriptields 2>/dev/null; bazel config extra_arg
# after
bazel help; bazel config

# Shell: strip non-flag args for options-only commands
args="$(printf '%s\n' "$@" | grep -E '^--?[^ ]*' | tr '\n' ' ')"
bazel config $args

If invoking the parser programmatically with allowResidue=false, pre-filter argv and treat residue as user data passed separately rather than letting the exception abort parsing.

When it happens

Trigger: Calling OptionsParser.newOptionsParser with a spec whose allowResidue() returns false (e.g. Blaze's options-only commands like 'help' or 'config') and then passing non-flag arguments, or an unknown flag that a preprocessor moved to residue.

Common situations: Running a Bazel command that accepts no target patterns (e.g. `bazel version foo`); passing a misspelled flag on a command where residue is disallowed; scripts forwarding unfiltered user args to an options-only invocation.

Related errors

• Invalid options syntax: %s
• '" + input + "' is not a boolean
• '" + input + "' is not an int
• '" + input + "' is not a long
• '" + input + "' is not a double

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