{"record":{"id":"14366ee79335133a","repo":"bazelbuild/bazel","slug":"unrecognized-arguments","errorCode":null,"errorMessage":"Unrecognized arguments: ","messagePattern":"Unrecognized arguments: ","errorType":"exception","errorClass":"OptionsParsingException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/google/devtools/common/options/OptionsParser.java","lineNumber":717,"sourceCode":"    Preconditions.checkNotNull(\n        optionToExpand, \"Option for expansion not specified for arglist %s\", args);\n    Preconditions.checkArgument(\n        optionToExpand.getPriority().getPriorityCategory()\n            != OptionPriority.PriorityCategory.DEFAULT,\n        \"Priority cannot be default, which was specified for arglist %s\",\n        args);\n    OptionsParserImplResult optionsParserImplResult =\n        impl.parseArgsAsExpansionOfOption(optionToExpand, o -> source, args);\n    addResidueFromResult(optionsParserImplResult);\n    return optionsParserImplResult.ignoredArgs;\n  }\n\n  private void addResidueFromResult(OptionsParserImplResult result) throws OptionsParsingException {\n    residue.addAll(result.getResidue());\n    postDoubleDashResidue.addAll(result.postDoubleDashResidue);\n    if (!allowResidue && !residue.isEmpty()) {\n      String errorMsg = \"Unrecognized arguments: \" + Joiner.on(' ').join(residue);\n      throw new OptionsParsingException(errorMsg);\n    }\n  }\n\n  /**\n   * Sets provided value for a flag with a particular priority. This only sets the value of the flag\n   * itself and does not affect any of its implicit requirements or expansions.\n   *\n   * @param origin the origin of this option instance, it includes the priority of the value. If\n   *     other values have already been or will be parsed at a higher priority, they might override\n   *     the provided value. If this option already has a value at this priority, this value will\n   *     have precedence, but this should be avoided, as it breaks order tracking.\n   * @param option the option to add the value for.\n   * @param value the value to add at the given priority.\n   */\n  void setOptionValueAtSpecificPriorityWithoutExpansion(\n      OptionInstanceOrigin origin, OptionDefinition option, String value)\n      throws OptionsParsingException {\n    impl.setOptionValueAtSpecificPriorityWithoutExpansion(origin, option, value);","sourceCodeStart":699,"sourceCodeEnd":735,"githubUrl":"https://github.com/bazelbuild/bazel/blob/e6e199d0601a244511b4cf18c8b2828aa73db1fd/src/main/java/com/google/devtools/common/options/OptionsParser.java#L699-L735","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the non-option arguments from the command line; move target patterns after '--' only if the command actually accepts them","Check for a misspelled or unavailable flag — unknown flags on residue-free commands surface this way; run with --help to list valid flags","If you are the command author and targets are legitimate, set allowResidue() to true in your OptionsModule/OptionsBase spec"],"exampleFix":"# before\nbazel help --scriptields 2>/dev/null; bazel config extra_arg\n# after\nbazel help; bazel config","handlingStrategy":"validation","validationCode":"# Shell: strip non-flag args for options-only commands\nargs=\"$(printf '%s\\n' \"$@\" | grep -E '^--?[^ ]*' | tr '\\n' ' ')\"\nbazel config $args","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Consult `bazel help command` to learn whether the command accepts targets/residue","Validate argv in wrappers: flags only for options-only commands","Use '--' explicitly to separate options from positional arguments where supported"],"tags":["bazel","options","residue","flag-parsing","cli"],"backgroundTag":null,"analyzedSha":"e6e199d0601a244511b4cf18c8b2828aa73db1fd","analyzedAt":"2026-08-14T10:24:27.848Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}