ben-manes/caffeine · error · IllegalArgumentException

Invalid option

Error message

Invalid option 

What it means

CaffeineSpec.parse dispatches each key=value pair of the spec string to a fixed set of options (initialCapacity, maximumSize, expireAfterAccess, etc.); any key that matches none of the switch cases throws IllegalArgumentException("Invalid option " + option). It indicates a typo'd or unsupported option name in the CaffeineSpec configuration string.

Source

Thrown at caffeine/src/main/java/com/github/benmanes/caffeine/cache/CaffeineSpec.java:204

        valueStrength(key, value, Strength.WEAK);
        return;
      case "softValues":
        valueStrength(key, value, Strength.SOFT);
        return;
      case "expireAfterAccess":
        expireAfterAccess(key, value);
        return;
      case "expireAfterWrite":
        expireAfterWrite(key, value);
        return;
      case "refreshAfterWrite":
        refreshAfterWrite(key, value);
        return;
      case "recordStats":
        recordStats(value);
        return;
      default:
        throw new IllegalArgumentException("Invalid option " + option);
    }
  }

  /** Configures the initial capacity. */
  void initialCapacity(String key, @Nullable String value) {
    requireArgument(initialCapacity == null,
        "initial capacity was already set to %,d", initialCapacity);
    initialCapacity = parseInt(key, value);
  }

  /** Configures the maximum size. */
  void maximumSize(String key, @Nullable String value) {
    requireArgument(maximumSize == null,
        "maximum size was already set to %,d", maximumSize);
    requireArgument(maximumWeight == null,
        "maximum weight was already set to %,d", maximumWeight);
    maximumSize = parseLong(key, value);
  }

View on GitHub (pinned to 9da6581ee3)

Solutions

1. Check the exception message: it names the exact invalid option string
2. Correct the key against the supported set: initialCapacity, maximumSize, maximumWeight, expireAfterAccess, expireAfterWrite, refreshAfterWrite, recordStats, strength keys (weakKeys/weakValues/softValues), and expiry variants
3. If specs come from user input/config files, validate keys against CaffeineSpec.supportedOptions before calling parse

Example fix

// before
Cache<K, V> cache = Caffeine.from("maximumsize=100,expireAfterWrite=10m")
    .build(); // IllegalArgumentException: Invalid option maximumsize=100

// after
Cache<K, V> cache = Caffeine.from("maximumSize=100,expireAfterWrite=10m")
    .build();

// Validate spec keys before parsing:
Set<String> supported = Set.of("initialCapacity", "maximumSize", "maximumWeight",
    "expireAfterAccess", "expireAfterWrite", "refreshAfterWrite", "recordStats",
    "weakKeys", "weakValues", "softValues", "strongKeys", "strongValues", "expireAfterAccessCustom", "expireAfterWriteCustom");
for (String entry : spec.split(",")) {
  String key = entry.split("=", 2)[0].strip();
  if (!supported.contains(key)) {
    throw new ConfigException("Unknown Caffeine option: " + key);
  }
}
Cache<K, V> cache = Caffeine.from(spec).build();

try {
  return Caffeine.from(spec);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Invalid option")) {
    throw new ConfigurationException("Bad Caffeine spec option: " + e.getMessage(), e);
  }
  throw e;
}

When it happens

Trigger: Calling Caffeine.from(spec) / CaffeineSpec.parse with a key not in the supported set, e.g. "maximumWeightSize=100", "expireAfterRead=30s", "maximumsize=100" (wrong case), or trailing separators producing an empty key.

Common situations: Migrating config from another cache library (Guava/Ehcache) and reusing old option names; typos in externally supplied spec strings (properties files, env vars); copy-pasting spec syntax from a newer/older Caffeine version with different option names.

Related errors

• key %s value was set to %s, must be an integer
• key %s value was set to %s, must be a long
• key %s invalid format; was %s, but the duration cannot be pa
• key %s invalid format; was %s, must end with one of [dDhHmMs
• throw new ExceptionInInitializerError(e)

AI-assisted analysis of ben-manes/caffeine@9da6581ee3 (2026-08-14). Data as JSON: /api/errors/414d1be5809548c0. Report an issue: GitHub.