bazelbuild/bazel · error · OptionsParsingException

Flag value '%s' for %s is not allowed by invocation policy a

Error message

Flag value '%s' for %s is not allowed by invocation policy and the policy does not specify a new value. %sed values are: %s

What it means

Thrown in checkUserValue (single-value branch) when the user-set value of a flag is not allowed by the allow_values/disallow_values policy and the policy provides neither a newValue nor use_default. Unlike error 38 this covers single-valued flags: the user's value is rejected and there is no policy fallback to substitute.

Source

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

          if (newValue != null) {
            logger.at(loglevel).log(
                "Overriding disallowed value '%s' for %s with value '%s' "
                    + "specified by invocation policy. %sed values are: %s",
                valueDescription.getValue(), option, newValue, policyType, policyValues);
            parser.clearValue(option);
            parser.setOptionValueAtSpecificPriorityWithoutExpansion(origin, option, newValue);
            invocationPolicyFlagListBuilder.add(
                OptionAndRawValue.create(option.getOptionName(), newValue));
          } else if (useDefault) {
            applyUseDefaultOperation(
                parser,
                policyType + "Values",
                option,
                loglevel,
                conversionContext,
                invocationPolicyFlagListBuilder);
          } else {
            throw new OptionsParsingException(
                String.format(
                    "Flag value '%s' for %s is not allowed by invocation policy and the "
                        + "policy does not specify a new value. %sed values are: %s",
                    valueDescription.getValue(), option, policyType, policyValues));
          }
        }
      }
    }
  }
}

View on GitHub (pinned to e6e199d060)

Solutions

Change the command-line/.bazelrc value to one in the '%sed values' list printed by the error.
Policy owner: add newValue to auto-remap disallowed values, or widen the allowed set.
Check user-level ~/.bazelrc and project .bazelrc for the offending flag before assuming the command line is the source.

Example fix

# before (policy allows only opt)
bazel build --compilation_mode=dbg //...

# after
bazel build --compilation_mode=opt //...

Defensive patterns

Strategy: validation

Validate before calling

// Wrapper-side: validate scalar flag value against the policy set before invoking
Set<String> allowed = loadPolicyAllowedValues(flagName);
String userVal = explicitValueFor(flagName, args, rcFiles);
if (userVal != null && !allowed.contains(userVal)) {
  throw new IllegalArgumentException(flagName + " must be one of " + allowed);
}

Try / catch

Catch OptionsParsingException; the message prints the offending value and the allowed list — surface both and point the user at every source of the flag (CLI, project .bazelrc, user ~/.bazelrc, aliases).

Prevention

Align personal .bazelrc values with the org allow-list
Policy owners: use newValue/use_default to remap rather than fail when feasible
Search all rc files (bazel's --announce_rc) when the command line looks clean

When it happens

Trigger: Policy restricts a scalar flag (e.g. allowValues=['opt'] on compilation_mode); user passes a different value (dbg); policy has no newValue and no useDefault -> the else branch throws after the newValue/useDefault checks fail.

Common situations: Org allow-lists on flags like compilation_mode/strategy where users habitually pass other values, developer machines with personal .bazelrc values that violate newly rolled-out policy, CI matrix jobs iterating values only some of which are allowed.

Related errors

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