bazelbuild/bazel · error · OptionsParsingException

%sValues policy disallows the default value '%s' for %s but

Error message

%sValues policy disallows the default value '%s' for %s but also specifies to use the default value

What it means

Thrown in the values-checking path (checkDefaultValue) when an allow_values/disallow_values policy both disallows the flag's default value and sets use_default — a contradictory policy (use the default that you forbid). Skipped for repeatable flags (default is always empty list) and special-null-default flags, where 'unset' is treated as always allowed.

Source

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

        }
      }

      // Check that if the default value of the flag is disallowed by the policy, that the policy
      // does not also set use_default. Otherwise the default value would still be set if the
      // user uses a disallowed value. This doesn't apply to repeatable flags since the default
      // value for repeatable flags is always the empty list. It also doesn't apply to flags that
      // are null by default, since these flags' default value is not parsed by the converter, so
      // there is no guarantee that there exists an accepted user-input value that would also set
      // the value to NULL. In these cases, we assume that "unset" is a distinct value that is
      // always allowed.
      if (!optionDescription.getOptionDefinition().allowsMultiple()
          && !optionDescription.getOptionDefinition().isSpecialNullDefault()) {
        boolean defaultValueAllowed =
            isFlagValueAllowed(
                convertedPolicyValues,
                optionDescription.getOptionDefinition().getDefaultValue(conversionContext));
        if (!defaultValueAllowed && useDefault) {
          throw new OptionsParsingException(
              String.format(
                  "%sValues policy disallows the default value '%s' for %s but also specifies to "
                      + "use the default value",
                  policyType,
                  optionDefinition.getDefaultValue(conversionContext),
                  optionDefinition));
        }
      }

      if (valueDescription == null) {
        // Nothing has set the value yet, so check that the default value from the flag's
        // definition is allowed. The else case below (i.e. valueDescription is not null) checks for
        // the flag allowing multiple values, however, flags that allow multiple values cannot have
        // default values, and their value is always the empty list if they haven't been specified,
        // which is why new_default_value is not a repeated field.
        checkDefaultValue(
            parser,
            origin,

View on GitHub (pinned to e6e199d060)

Solutions

Remove use_default from the policy entry, or extend the allowed set / shrink the disallowed set so the flag's default is permitted.
Supply a newValue in disallow_values so the default is replaced rather than 'used'.
Check the flag's default (bazel help) whenever writing allow/disallow policies against it.

Example fix

// before (default is fastbuild)
{"flagName":"compilation_mode","allowValues":{"allowedValues":["opt"]},"useDefault":true}

// after
{"flagName":"compilation_mode","allowValues":{"allowedValues":["opt"]}}

Defensive patterns

Strategy: validation

Validate before calling

// Lint: use_default together with a default-disallowing allow/disallow set is contradictory
Object def = optionDefinition.getDefaultValue(ctx);
if (usesUseDefault(fp) && !isValueAllowedByPolicy(fp, def)) {
  throw new IllegalStateException("Policy forbids the default but also sets use_default");
}

Try / catch

Catch OptionsParsingException at policy enforcement; resolve the contradiction by removing use_default or allowing the default value.

Prevention

Never pair use_default with a value set that excludes the flag's default
Look up each flag's default in bazel help before writing allow/disallow policies
Provide newValue instead of use_default when replacing a disallowed default

When it happens

Trigger: Policy on a single-valued flag with a non-null default: disallowValues lists the default value (without newValue) plus useDefault=true; or allowValues omits the default plus useDefault=true. E.g. flag default 'fastbuild', policy allows only ['opt'] and says use default — contradiction.

Common situations: Policy authors restricting a flag to a value while reflexively adding use_default as a 'safe fallback', porting policies between flags with different defaults without re-checking the default value, generated policies that always set both fields.

Related errors

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