bazelbuild/bazel · error · OptionsParsingException

Disallow_Values on expansion flags like %s is not allowed.

Error message

Disallow_Values on expansion flags like %s is not allowed.

What it means

Thrown by throwDisallowValuesOnExpansionFlagException when an invocation policy applies a disallow_values operation to an expansion flag. Expansion flags carry no value of their own (they only expand to child flags), so disallowing specific values on them cannot be enforced and is rejected. Note: in the sub-flag propagation path (line ~532) DISALLOW_VALUES on an implicit requirement is silently skipped, but a direct policy on the expansion flag itself throws.

Source

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

    // 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
            ));
  }

  /**
   * Expand a single policy. If the policy is not about an expansion flag, this will simply return a
   * list with a single element, oneself. If the policy is for an expansion flag, the policy will
   * get split into multiple policies applying to each flag the original flag expands to.
   *
   * <p>None of the flagPolicies returned should be on expansion flags.

View on GitHub (pinned to e6e199d060)

Solutions

Remove the disallow_values operation on the expansion flag.
Target the child flags the expansion produces (disallow compilation_mode=opt rather than the mode shorthand).
Verify flag expansion behavior in the current Bazel version with bazel help before authoring policy.

Example fix

// before
{"flagName":"opt","disallowValues":{"disallowedValues":["opt"]}}

// after
{"flagName":"compilation_mode","disallowValues":{"disallowedValues":["opt"],"newValue":["fastbuild"]}}

Defensive patterns

Strategy: validation

Validate before calling

// Check the flag is not an expansion flag before authoring disallow_values
if (optionDefinition.hasExpansion() && policyEntry.hasDisallowValues()) {
  throw new IllegalStateException("disallow_values cannot target expansion flag " + flagName);
}

Try / catch

Catch OptionsParsingException from policy enforcement; retarget the disallow_values operation to the child flags the expansion produces.

Prevention

Disallow the child flag values instead of the shorthand
Keep a version-pinned map of expansion flags for policy authoring
Smoke-test policies with a trivial bazel command before org-wide rollout

When it happens

Trigger: A policy entry with flagName matching an expansion flag and a disallowValues operation present, e.g. {"flagName":"opt","disallowValues":{"disallowedValues":["opt"]}}.

Common situations: Trying to forbid a shorthand mode flag (e.g. disallow --opt) in org policy instead of its child flags, policies written against old flag semantics where the flag was not yet an expansion flag.

Related errors

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