What causes "Unknown cache configuration property: {}" in apache/maven?

Restrict keys inside the curly-brace selector block to scope=..., ref=..., or reference=...

Unknown cache configuration property: {}

Error message

Unknown cache configuration property: {}

What it means

While parsing the selector configuration language for Maven's internal caches (-Dmaven.cache.config=...), CacheSelectorParser matched a key=value pair whose key is neither 'scope' nor 'ref'/'reference'. The unknown key is announced and otherwise ignored, producing a PartialCacheConfig with only the recognized keys set. It is a syntax-typo guard: recognized keys still take effect, so behavior silently diverges from what the user believes they configured.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/cache/CacheSelectorParser.java:122

    private static PartialCacheConfig parseProperties(String properties) {
        CacheRetention scope = null;
        Cache.ReferenceType referenceType = null;

        Matcher propMatcher = PROPERTY_PATTERN.matcher(properties);
        while (propMatcher.find()) {
            String key = propMatcher.group(1);
            String value = propMatcher.group(2);

            switch (key.toLowerCase(Locale.ENGLISH)) {
                case "scope":
                    scope = parseScope(value);
                    break;
                case "ref":
                case "reference":
                    referenceType = parseReferenceType(value);
                    break;
                default:
                    LOGGER.warn("Unknown cache configuration property: {}", key);
            }
        }

        // Return partial configuration (null values are allowed)
        return new PartialCacheConfig(scope, referenceType);
    }

    /**
     * Parses a scope string into CacheRetention.
     */
    private static CacheRetention parseScope(String value) {
        return switch (value.toLowerCase(Locale.ENGLISH)) {
            case "session" -> CacheRetention.SESSION_SCOPED;
            case "request" -> CacheRetention.REQUEST_SCOPED;
            case "persistent" -> CacheRetention.PERSISTENT;
            case "disabled", "none" -> CacheRetention.DISABLED;
            default -> {
                LOGGER.warn("Unknown cache scope: {}, using default REQUEST_SCOPED", value);

View on GitHub (pinned to e4093d4e12)

Solutions

Restrict keys inside the curly-brace selector block to scope=..., ref=..., or reference=...
Remove the unknown key and re-run; the warning disappears when every key is recognized
Check the Maven cache configuration documentation for the current key set after upgrading Maven

Example fix

# before: 'refs' is not a recognized key, silently ignored
mvn clean install '-Dmaven.cache.config=**{scope=session,refs=hard}'

# after: recognized keys only
mvn clean install '-Dmaven.cache.config=**{scope=session,reference=hard}'

Defensive patterns

Strategy: validation

Validate before calling

# Validate the selector grammar before passing it to Maven
import re, sys
cfg = sys.argv[1]  # e.g. '**{scope=session,reference=hard}'
for m in re.finditer(r'\{([^}]*)\}', cfg):
    for kv in m.group(1).split(','):
        key = kv.split('=')[0].strip().lower()
        if key not in ('scope', 'ref', 'reference'):
            sys.exit(f"unknown cache config key '{key}' in {cfg}")

Type guard

boolean isKnownCacheKey(String key) {
    return switch (key.toLowerCase(Locale.ENGLISH)) {
        case "scope", "ref", "reference" -> true;
        default -> false;
    };
}

Prevention

Keep selector blocks limited to the documented keys scope, ref, reference
Copy cache config from the official docs rather than composing it from memory
After any cache config change, run one cheap build and confirm zero cache-configuration warnings

When it happens

Trigger: Writing -Dmaven.cache.config=<selector>{scope=session,refs=soft}: the key 'refs' (invalid) is skipped while 'scope' is honored. Any key other than scope/ref/reference hits the default branch of the switch.

Common situations: Guessing property names instead of consulting the cache configuration docs ('type=', 'ttl=', 'refs='); stale config from an older Maven where the key set differed; copy-paste between projects with divergent Maven versions.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/8ffe820febcc52bc. Report an issue: GitHub.