bazelbuild/bazel · error · OptionsParsingException

User set a value for %s which is not permitted by the invoca

Error message

User set a value for %s which is not permitted by the invocation policy. This flag value will always be overridden to %s. %s

What it means

Thrown when set_value has behavior FINAL_VALUE_THROW_ON_OVERRIDE and the user explicitly set the flag on the command line. The policy's value is final; a user-supplied value conflicts, so parsing aborts rather than silently overriding. The message includes the option definition, the policy-mandated values, and any customErrorMessage the policy author set.

Source

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

              "Keeping value '%s' from source '%s' for %s because the invocation policy specifying "
                  + "the value(s) '%s' is overridable",
              valueDescription.getValue(),
              valueDescription.getSourceString(),
              optionDefinition,
              setValue.getFlagValueList());
          // Nothing to do -- the value already has an override.
          return;
        }
        break;
      case FINAL_VALUE_IGNORE_OVERRIDES:
        // Clear the value in case the flag is a repeated flag so that values don't accumulate.
        parser.clearValue(flagPolicy.description.getOptionDefinition());
        break;
      case APPEND:
        break;
      case FINAL_VALUE_THROW_ON_OVERRIDE:
        if (valueDescription != null) {
          throw new OptionsParsingException(
              String.format(
                  "User set a value for %s which is not permitted by the invocation policy. This"
                      + " flag value will always be overridden to %s. %s",
                  optionDefinition,
                  flagPolicy.policy.getSetValue().getFlagValueList(),
                  flagPolicy.policy.getCustomErrorMessage()));
        }
        break;
    }

    // Set all the flag values from the policy.
    for (String flagValue : setValue.getFlagValueList()) {
      if (valueDescription == null) {
        logger.at(loglevel).log(
            "Setting value for %s from invocation policy to '%s', overriding the default value "
                + "'%s'",
            optionDefinition, flagValue, optionDefinition.getDefaultValue(conversionContext));
      } else {

View on GitHub (pinned to e6e199d060)

Solutions

Remove the user-supplied flag from the command line / script / .bazelrc and accept the policy value.
If you own the policy and the flag should be user-settable, change behavior to ALLOW_OVERRIDES.
If it must stay final but with a clearer failure, set custom_message on the policy entry so users see instructions in this very error.
Audit user-level .bazelrc files and aliases for the locked flag name.

Example fix

# before (policy forces compilation_mode=opt, FINAL_VALUE_THROW_ON_OVERRIDE)
bazel build --compilation_mode=dbg //...

# after
bazel build //...

Defensive patterns

Strategy: try-catch

Validate before calling

// Wrapper-side guard: drop flags known to be policy-final before invoking bazel
Set<String> policyLockedFlags = loadFromOrgPolicy();
List<String> safeArgs = userArgs.stream()
    .filter(a -> !policyLockedFlags.contains(flagNameOf(a)))
    .collect(toList());

Try / catch

Catch OptionsParsingException, detect the 'not permitted by the invocation policy' prefix, and fail with actionable guidance: name the locked flag and the policy-mandated value (both are in the message) and instruct removal of the user flag. Do not auto-strip and retry unless the wrapper owns the offending args.

Prevention

Publish the list of policy-final flags to all developers
Set customErrorMessage in the policy so this error self-documents the fix
Wrapper scripts should filter out locked flags instead of passing them blindly

When it happens

Trigger: Org policy pins a flag with FINAL_VALUE_THROW_ON_OVERRIDE; a developer then passes that flag on the command line (e.g. policy forces --compilation_mode=opt, user runs bazel build --compilation_mode=dbg).

Common situations: CI or corporate environments with enforced policies where local habits/scripts pass the locked flag, developer unaware the flag is locked, wrapper scripts unconditionally adding flags that are policy-pinned.

Related errors

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