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

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.

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.

Appendix: 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)