What causes "Invalid options syntax: %s" in bazelbuild/bazel?

Inspect the exact token reported in the message and restore the missing flag name

bazelbuild/bazel · error · OptionsParsingException

Invalid options syntax: %s

Error message

Invalid options syntax: %s

What it means

Thrown while parsing a '--'-prefixed token when the option name between '--' and '=' is empty or only whitespace, e.g. '--=value' or '-- =x'. The long-option branch extracts the name after the two dashes; an empty name has no corresponding option definition so parsing cannot continue.

Source

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

    boolean booleanValue = true;
    String parsedOptionName = "";

    if (arg.length() == 2) { // -l  (may be nullary or unary)
      lookupResult = getWithFallback(OptionsData::getFieldForAbbrev, arg.charAt(1), fallbackData);
      booleanValue = true;

    } else if (arg.length() == 3 && arg.charAt(2) == '-') { // -l-  (boolean)
      lookupResult = getWithFallback(OptionsData::getFieldForAbbrev, arg.charAt(1), fallbackData);
      booleanValue = false;

    } else if (arg.startsWith("--")) { // --long_option

      int equalsAt = arg.indexOf('=');
      int nameStartsAt = 2;
      String name =
          equalsAt == -1 ? arg.substring(nameStartsAt) : arg.substring(nameStartsAt, equalsAt);
      if (name.trim().isEmpty()) {
        throw new OptionsParsingException("Invalid options syntax: " + arg, arg);
      }
      unconvertedValue = equalsAt == -1 ? null : arg.substring(equalsAt + 1);
      lookupResult = getWithFallback(OptionsData::getOptionDefinitionFromName, name, fallbackData);

      // Look for a "no"-prefixed option name: "no<optionName>".
      if (lookupResult == null && name.startsWith("no")) {
        name = name.substring(2);
        lookupResult =
            getWithFallback(OptionsData::getOptionDefinitionFromName, name, fallbackData);
        booleanValue = false;
        if (lookupResult != null) {
          if (!lookupResult.definition.usesBooleanValueSyntax()) {
            throw new OptionsParsingException(
                "Illegal use of 'no' prefix on non-boolean option: " + arg, arg);
          }
          if (unconvertedValue != null) {
            throw new OptionsParsingException("Unexpected value after boolean option: " + arg, arg);
          }

View on GitHub (pinned to e6e199d060)

Solutions

Inspect the exact token reported in the message and restore the missing flag name
In scripts, guard flag construction: skip or error when the name variable is empty (e.g. [ -n "$name" ] before emitting --$name=$value)
Enable shell strictness (set -u / nounset) so unset variables fail at generation time

Example fix

# before
bazel build --${FLAG_NAME}=opt //...
# after
[ -n "$FLAG_NAME" ] || { echo 'FLAG_NAME unset' >&2; exit 1; }
bazel build --${FLAG_NAME}=opt //...

Defensive patterns

Strategy: validation

Validate before calling

# Reject tokens with an empty flag name before invoking
for arg in "$@"; do
  case "$arg" in
    --[=\ ]*|--=*) echo "Empty option name in: $arg" >&2; exit 2;;
  esac
done

Prevention

Build flags as a single '--name=value' token so an empty name is impossible
Fail scripts on unset variables (set -u)
Echo the final argv before execution during debugging

When it happens

Trigger: Passing a token like `--=foo`, `-- =foo`, or a shell variable that expands to nothing between the dashes, e.g. `--${EMPTY_VAR}=value`.

Common situations: Script-generated command lines where a flag-name variable is unset or empty; accidental deletion of the flag name when editing a command; copy-paste artifacts like '--=true'.

Related errors

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