bazelbuild/bazel · error · OptionsParsingException

Variable definitions must be in the form of a 'name=value' a

Error message

Variable definitions must be in the form of a 'name=value' assignment

What it means

Thrown by AssignmentConverter when a command-line variable definition does not contain a '=' character, or the '=' is the first character (position 0, meaning an empty name). The converter splits input at the first '=' to produce a Map.Entry<name, value>, so input without a usable separator cannot be parsed. It is raised as an OptionsParsingException during flag parsing.

Source

Thrown at src/main/java/com/google/devtools/common/options/Converters.java:513

            + "-"
            + maxValue
            + " range";
      }
    }
  }

  /**
   * A converter for variable assignments from the parameter list of a blaze command invocation.
   * Assignments are expected to have the form "name=value", where names and values are defined to
   * be as permissive as possible.
   */
  public static class AssignmentConverter extends Converter.Contextless<Map.Entry<String, String>> {

    @Override
    public Map.Entry<String, String> convert(String input) throws OptionsParsingException {
      int pos = input.indexOf("=");
      if (pos <= 0) {
        throw new OptionsParsingException(
            "Variable definitions must be in the form of a 'name=value' assignment");
      }
      String name = input.substring(0, pos);
      String value = input.substring(pos + 1);
      return Maps.immutableEntry(name, value);
    }

    @Override
    public String getTypeDescription() {
      return "a 'name=value' assignment";
    }
  }

  /** A converter for for assignments from a string value to a float value. */
  public static class StringToDoubleAssignmentConverter
      extends Converter.Contextless<Map.Entry<String, Double>> {
    private static final AssignmentConverter baseConverter = new AssignmentConverter();

View on GitHub (pinned to e6e199d060)

Solutions

  1. Fix the argument to the exact form name=value, e.g. --define=VERSION=1.2 instead of --define=VERSION.
  2. Check shell quoting: quote the whole flag (--define="NAME=va lue") so the shell does not split it.
  3. If the value is generated from a variable, verify it is non-empty and contains '=' before passing it (echo "$arg" | grep '=').
  4. Audit scripts/CI config for lines that append to --define / --repo_env without validating the name=value shape.

Example fix

# before
bazel build --define=COMPILE_MODE

# after
bazel build --define=COMPILE_MODE=OPT
Defensive patterns

Strategy: validation

Validate before calling

// Java: validate assignment shape before passing as a flag value
boolean isValidAssignment(String s) {
  int pos = s == null ? -1 : s.indexOf("=");
  return pos > 0; // '=' present and not first char, mirroring pos <= 0 rejection
}
List<String> args = rawArgs.stream().filter(this::isValidAssignment).collect(toList());

Try / catch

catch (OptionsParsingException e) when constructing the option value: log e.getMessage() (it names the malformed input path) and surface which flag argument failed; do not retry with the same string.

Prevention

When it happens

Trigger: Passing a flag value accepted by AssignmentConverter that lacks '=' (e.g. --define=FOO or --repo_env=PATH) or starts with '=' (=VALUE, since pos <= 0 rejects position 0). Any blaze/bazel command-line option whose converter is AssignmentConverter (e.g. --define, --repo_env, --action_env in some usages) with a malformed argument.

Common situations: Typos in --define flags (missing '=' or space instead of '='), shell quoting that strips the '=' or splits the argument, scripts generating flag lists that emit an empty name, CI pipelines building --define args from unset environment variables.

Related errors

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