bazelbuild/bazel · error · OptionsParsingException

Failed to parse CaffeineSpec: " + e.getMessage()

Error message

Failed to parse CaffeineSpec: " + e.getMessage()

What it means

Thrown by CaffeineSpecConverter when CaffeineSpec.parse(spec) raises IllegalArgumentException, i.e. the string is not a valid Caffeine cache specification. CaffeineSpec has its own strict grammar (keys like maximumSize, expireAfterAccess with '=' pairs separated by ','); any syntax or unknown-key error is wrapped into an OptionsParsingException with the underlying reason appended.

Source

Thrown at src/main/java/com/google/devtools/common/options/Converters.java:667

    @Override
    public OptionalInt convert(String input) throws OptionsParsingException {
      return input.equals(UNSET)
          ? OptionalInt.empty()
          : OptionalInt.of(PERCENTAGE_CONVERTER.convert(input));
    }
  }

  /**
   * A {@link Converter} for {@link com.github.benmanes.caffeine.cache.CaffeineSpec}. The spec may
   * be empty, in which case this converter returns null.
   */
  public static final class CaffeineSpecConverter extends Converter.Contextless<CaffeineSpec> {
    @Override
    public CaffeineSpec convert(String spec) throws OptionsParsingException {
      try {
        return CaffeineSpec.parse(spec);
      } catch (IllegalArgumentException e) {
        throw new OptionsParsingException("Failed to parse CaffeineSpec: " + e.getMessage(), e);
      }
    }

    @Override
    public String getTypeDescription() {
      return "Converts to a CaffeineSpec, or null if the input is empty";
    }
  }

  /** A {@link Converter} for a size in bytes with an optional multiplier suffix. */
  public static final class ByteSizeConverter extends Converter.Contextless<Long> {
    private static final Pattern PATTERN =
        Pattern.compile("(?<value>[0-9]+)(?<multiplier>[KMGT]?)");

    private static final ImmutableMap<String, Long> MULTIPLIER_MAP =
        ImmutableMap.of(
            "K",
            1024L,

View on GitHub (pinned to e6e199d060)

Solutions

1. Read the appended e.getMessage() from Caffeine — it states the exact parse failure position and expected grammar.
2. Correct the spec to Caffeine grammar: comma-separated key=value pairs, e.g. maximumSize=512,expireAfterAccess=3600s.
3. For size-style flags, use ByteSizeConverter-typed flags (e.g. '1G', '512M') instead of Caffeine-spec flags; check the flag's getTypeDescription().
4. If the spec should be empty/default, pass an empty value rather than a placeholder like 'default'.

Example fix

# before
--experimental_action_cache=100MB

# after
--experimental_action_cache=maximumSize=104857600

// Pre-flight the spec with Caffeine itself before handing it to the flag
try {
  com.github.benmanes.caffeine.cache.CaffeineSpec.parse(spec);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Bad cache spec '" + spec + "': " + e.getMessage(), e);
}

Catch OptionsParsingException; the wrapped cause is the original IllegalArgumentException from Caffeine — read e.getCause().getMessage() for the precise parse failure and fix the spec string.

When it happens

Trigger: Passing a malformed spec to a flag typed CaffeineSpecConverter, e.g. --experimental_repository_cache_hard_limit=100MB (wrong unit grammar), maximumSize=abc, spec with unknown option key, or missing '=' in a key-value pair. The empty string is valid and returns null.

Common situations: Confusing Caffeine spec syntax with byte-size syntax (using '1G' where Caffeine expects a plain number for maximumSize), typos in spec keys, using a newer/older flag name whose accepted keys changed between Bazel versions.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Variable definitions must be in the form of a 'name=value' a
• Must be in the form of a 'key=value[,value]' assignment
• Variable definitions must not contain empty strings or leadi
• Invalid size: " + input
• Not a valid %s: '%s' (should be %s)

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