bazelbuild/bazel · error · OptionsParsingException

Allow_Values on expansion flags like %s is not allowed.

Error message

Allow_Values on expansion flags like %s is not allowed.

What it means

Thrown by throwAllowValuesOnExpansionFlagException when an invocation policy applies an allow_values operation to an expansion flag (a flag whose only job is to expand into other flags, like --fastbuild or --opt-style shorthand flags). Constraining values on an expansion flag is meaningless/impossible to enforce, so it is rejected outright.

Source

Thrown at src/main/java/com/google/devtools/common/options/InvocationPolicyEnforcer.java:301

      FlagPolicyWithContext policyWithContext =
          new FlagPolicyWithContext(policy, optionDescription, origin);
      List<FlagPolicyWithContext> policies = expandPolicy(policyWithContext, parser, loglevel);
      expandedPolicies.addAll(policies);
    }

    // Only keep that last policy for each flag.
    ImmutableMap.Builder<String, FlagPolicyWithContext> effectivePolicy = ImmutableMap.builder();
    for (FlagPolicyWithContext expandedPolicy : expandedPolicies) {
      String flagName = expandedPolicy.policy.getFlagName();
      effectivePolicy.put(flagName, expandedPolicy);
    }

    return effectivePolicy.buildKeepingLast().values().asList();
  }

  private static void throwAllowValuesOnExpansionFlagException(String flagName)
      throws OptionsParsingException {
    throw new OptionsParsingException(
        String.format("Allow_Values on expansion flags like %s is not allowed.", flagName));
  }

  private static void throwDisallowValuesOnExpansionFlagException(String flagName)
      throws OptionsParsingException {
    throw new OptionsParsingException(
        String.format("Disallow_Values on expansion flags like %s is not allowed.", flagName));
  }

  private static OptionsParsingException throwUndefinedBehaviorException(FlagPolicy policy)
      throws OptionsParsingException {
    throw new OptionsParsingException(
        String.format(
            "SetValue operation from invocation policy for has an undefined behavior: %s",
            policy
            ));
  }

View on GitHub (pinned to e6e199d060)

Solutions

  1. Remove the allow_values operation on the expansion flag.
  2. Apply allow_values to the concrete child flags the expansion expands into (e.g. compilation_mode instead of a mode shorthand).
  3. Run bazel help to confirm which flags are expansion flags in your version before writing policy.
  4. Keep policies version-pinned to the Bazel release they were written for.

Example fix

// before
{"flagName":"fastbuild","allowValues":{"allowedValues":["fastbuild"]}}

// after
{"flagName":"compilation_mode","allowValues":{"allowedValues":["fastbuild","dbg"]}}
Defensive patterns

Strategy: validation

Validate before calling

// Check the flag is not an expansion flag before authoring allow_values
// (isExpansion is determined from the option definition in the running binary)
if (optionDefinition.hasExpansion() && policyEntry.hasAllowValues()) {
  throw new IllegalStateException("allow_values cannot target expansion flag " + flagName);
}

Try / catch

Catch OptionsParsingException from policy enforcement; the message names the expansion flag — retarget the operation to its child flags.

Prevention

When it happens

Trigger: A policy entry with flagName equal to a known expansion flag and an allowValues operation set. Detected during policy expansion (expandPolicy) where the enforcer checks isExpansion before splitting policies onto child flags.

Common situations: Policy authors targeting shorthand flags (--fastbuild) instead of the real flags they expand to, policies written before a flag became an expansion flag (flag semantics changed across Bazel versions), auto-generated policies from flag inventories.

Related errors

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