bazelbuild/bazel · error · OptionsParsingException

Invalid options syntax: %s Note: Negative target patterns ca

Error message

Invalid options syntax: %s
Note: Negative target patterns can only appear after the end of options marker ('--'). Flags corresponding to Starlark-defined build settings always start with '--', not '-'.

What it means

OptionsParserImpl throws this dedicated error when a command-line token starts with '-//' or '-@' — shapes that look like an absolute negative target pattern or a typoed single-dash Starlark flag. Single-dash args are parsed as short options, so these would otherwise fail with a confusing 'Unrecognized option' message; the check gives the user the actual rule: negative patterns go after '--' and Starlark build settings use '--'.

Source

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

    List<String> ignoredArgs = new ArrayList<>();

    Iterator<ArgAndFallbackData> argsAndFallbackDataIterator =
        argsPreProcessor.preProcess(args).iterator();
    Iterator<String> argsIterator = Iterators.transform(argsAndFallbackDataIterator, a -> a.arg);
    while (argsAndFallbackDataIterator.hasNext()) {
      ArgAndFallbackData argAndFallbackData = argsAndFallbackDataIterator.next();
      String arg = argAndFallbackData.arg;
      @Nullable OptionsData fallbackData = argAndFallbackData.fallbackData;

      if (!arg.startsWith("-")) {
        unparsedArgs.add(arg);
        continue; // not an option arg
      }

      if (arg.startsWith("-//") || arg.startsWith("-@")) {
        // Fail with a helpful error when an invalid option looks like an absolute negative target
        // pattern or a typoed Starlark option.
        throw new OptionsParsingException(
            String.format(
                "Invalid options syntax: %s\n"
                    + "Note: Negative target patterns can only appear after the end of options"
                    + " marker ('--'). Flags corresponding to Starlark-defined build settings"
                    + " always start with '--', not '-'.",
                arg));
      }

      arg = swapShorthandAlias(arg);

      if (arg.equals("--")) { // "--" means all remaining args aren't options
        Iterators.addAll(unparsedPostDoubleDashArgs, argsIterator);
        break;
      }

      Optional<ParsedOptionDescription> parsedOption;
      if (containsSkippedPrefix(arg)) {
        // Parse the skipped arg into a synthetic allowMultiple option to preserve its order

View on GitHub (pinned to e6e199d060)

Solutions

1. For negative target patterns, place them after the end-of-options marker: `bazel build -- //... -//pkg:target`
2. For Starlark-defined build settings, use two dashes: `--//pkg:my_flag=value`
3. If you meant a short boolean option like -l, confirm the actual single-letter abbreviation with --help

Example fix

# before
bazel build //... -//third_party:conscrypt
# after
bazel build -- //... -//third_party:conscrypt

# Reject single-dash // or @ tokens before the end-of-options marker
for arg in "$@"; do
  case "$arg" in
    -//*|-@*) echo "Move negative patterns after '--' and use '--' for Starlark flags: $arg" >&2; exit 2;;
  esac
done

When it happens

Trigger: Passing '-//pkg:target' or '-@file.txt' before the '--' end-of-options marker; typing '--//pkg:setting' with one dash instead of two.

Common situations: Trying to exclude a target (e.g. `bazel build //... -//pkg:target` — correct form puts the exclusion after '--' or uses it in target position); muscle-memory single-dash typo for a Starlark build setting like -//pkg:my_flag.

Related errors

• Malformed value of --invocation_policy:
• Tried to expand option too many times
• Unrecognized arguments:
• Invalid options syntax: %s
• Illegal use of 'no' prefix on non-boolean option: %s

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