bazelbuild/bazel · error · OptionsParsingException

Default flag value '%s' for %s is not allowed by invocation

Error message

Default flag value '%s' for %s is not allowed by invocation policy, but the policy does not provide a new value. %sed values are: %s

What it means

Thrown in checkDefaultValue when an allow_values/disallow_values policy forbids the flag's default value, the user did not set the flag, and the policy supplies no replacement (no newValue, no use_default). The default cannot stay (disallowed) and nothing tells the enforcer what to use instead, so parsing fails. The message lists the policyType ('Allow'/'Disallow' rendered as '%sed values') and the permitted value set.

Source

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

          convertedPolicyValues, optionDefinition.getDefaultValue(conversionContext))) {
        if (newValue != null) {
          // Use the default value from the policy, since the original default is not allowed
          logger.at(loglevel).log(
              "Overriding default value '%s' for %s with value '%s' specified by invocation "
                  + "policy. %sed values are: %s",
              optionDefinition.getDefaultValue(conversionContext),
              optionDefinition,
              newValue,
              policyType,
              policyValues);
          parser.clearValue(optionDefinition);
          parser.setOptionValueAtSpecificPriorityWithoutExpansion(
              origin, optionDefinition, newValue);
          invocationPolicyFlagListBuilder.add(
              OptionAndRawValue.create(optionDefinition.getOptionName(), newValue));
        } else {
          // The operation disallows the default value, but doesn't supply a new value.
          throw new OptionsParsingException(
              String.format(
                  "Default flag value '%s' for %s is not allowed by invocation policy, but "
                      + "the policy does not provide a new value. %sed values are: %s",
                  optionDescription.getOptionDefinition().getDefaultValue(conversionContext),
                  optionDefinition,
                  policyType,
                  policyValues));
        }
      }
    }

    void checkUserValue(
        OptionsParser parser,
        OptionInstanceOrigin origin,
        OptionDescription optionDescription,
        OptionValueDescription valueDescription,
        List<String> policyValues,
        String newValue,

View on GitHub (pinned to e6e199d060)

Solutions

Add newValue to the allow/disallow operation so the default is replaced (e.g. disallowValues with newValue=['opt']).
Or add useDefault only if the default itself is allowed (see related contradiction error otherwise).
Or widen the allowed set to include the flag's default.
Communicate the forced value to users so their builds don't change silently.

Example fix

// before (default fastbuild is not in allowed set, no fallback)
{"flagName":"compilation_mode","allowValues":{"allowedValues":["opt"]}}

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

Defensive patterns

Strategy: validation

Validate before calling

// Lint: if the default is disallowed, policy must supply newValue or use_default (with default allowed)
Object def = optionDefinition.getDefaultValue(ctx);
if (!isValueAllowedByPolicy(fp, def)
    && !hasNewValue(fp)
    && !usesUseDefault(fp)) {
  throw new IllegalStateException("Policy forbids default of '" + flagName + "' with no fallback");
}

Try / catch

Catch OptionsParsingException; add newValue to the allow/disallow operation so unset users get a valid replacement automatically.

Prevention

Always supply newValue when restricting a flag whose default is outside the allowed set
Consider users who never set the flag when authoring value restrictions
Re-check defaults after Bazel upgrades, since defaults can change between versions

When it happens

Trigger: Policy {"flagName":"compilation_mode","allowValues":{"allowedValues":["opt"]}} with the flag's default 'fastbuild' and the user not passing the flag: default is checked, disallowed, no newValue/useDefault present -> throw.

Common situations: Org policy restricting a flag without considering that everyone who never sets the flag will now hard-fail, rolling out value restrictions to a large repo where most users rely on defaults, version changes that alter a flag's default value after the policy was written.

Related errors

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