What causes "Invalid key reference types '{}', using defaults" in apache/maven?

Correct the property to one of the accepted values: soft, hard, weak, or none (case-insensitive)

Invalid key reference types '{}', using defaults

Error message

Invalid key reference types '{}', using defaults

What it means

CacheConfigurationResolver read the user property maven.cache.keyValueRefs (Constants.MAVEN_CACHE_KEY_REFS) and tried Cache.ReferenceType.valueOf() on the upper-cased, trimmed value. Because the string does not match any enum constant (SOFT, HARD, WEAK, NONE), valueOf threw IllegalArgumentException; the warning is logged and keyRefType stays null so the cache uses its default reference type. Purely a configuration-typo diagnostic; the build proceeds.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/cache/CacheConfigurationResolver.java:65

     * @param req the request to resolve configuration for
     * @param session the session containing user properties
     * @return the resolved cache configuration
     */
    public static CacheConfig resolveConfig(Request<?> req, Session session) {
        // First check if request implements CacheMetadata for backward compatibility
        CacheRetention legacyRetention = null;
        if (req instanceof CacheMetadata metadata) {
            legacyRetention = metadata.getCacheRetention();
        }

        // Check for key reference type configuration
        Cache.ReferenceType keyRefType = null;
        String keyRefsString = session.getUserProperties().get(Constants.MAVEN_CACHE_KEY_REFS);
        if (keyRefsString != null && !keyRefsString.trim().isEmpty()) {
            try {
                keyRefType = Cache.ReferenceType.valueOf(keyRefsString.trim().toUpperCase());
            } catch (IllegalArgumentException e) {
                LOGGER.warn("Invalid key reference types '{}', using defaults", keyRefsString);
            }
        }

        // Check for value reference type configuration
        Cache.ReferenceType valueRefType = null;
        String valueRefsString = session.getUserProperties().get(Constants.MAVEN_CACHE_VALUE_REFS);
        if (valueRefsString != null && !valueRefsString.trim().isEmpty()) {
            try {
                valueRefType =
                        Cache.ReferenceType.valueOf(valueRefsString.trim().toUpperCase());
            } catch (IllegalArgumentException e) {
                LOGGER.warn("Invalid value reference types '{}', using defaults", valueRefsString);
            }
        }

        // Get user-defined configuration
        String configString = session.getUserProperties().get(Constants.MAVEN_CACHE_CONFIG_PROPERTY);
        if (configString == null || configString.trim().isEmpty()) {

View on GitHub (pinned to e4093d4e12)

Solutions

Correct the property to one of the accepted values: soft, hard, weak, or none (case-insensitive)
Check .mvn/maven.config and MAVEN_OPTS for the misspelled value
Omit the property entirely to use the default reference type

Example fix

# before
mvn clean install -Dmaven.cache.keyValueRefs=softref

# after
mvn clean install -Dmaven.cache.keyValueRefs=soft

Defensive patterns

Strategy: validation

Validate before calling

// Validate the user property before handing the session to Maven
String raw = session.getUserProperties().get("maven.cache.keyValueRefs");
if (raw != null && !raw.isBlank()) {
    try {
        Cache.ReferenceType.valueOf(raw.trim().toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException e) {
        throw new IllegalArgumentException(
            "maven.cache.keyValueRefs must be one of soft|hard|weak|none, got: " + raw);
    }
}

Type guard

static Optional<Cache.ReferenceType> asReferenceType(String s) {
    if (s == null) return Optional.empty();
    try {
        return Optional.of(Cache.ReferenceType.valueOf(s.trim().toUpperCase(Locale.ROOT)));
    } catch (IllegalArgumentException e) {
        return Optional.empty();
    }
}

Prevention

Restrict cache reference-type values to the four documented enum names
Centralize cache tuning in .mvn/maven.config and review it like code
Add a startup CI check: mvn -q help:evaluate-free-form or any cheap goal must not print cache-configuration warnings

When it happens

Trigger: Starting Maven with -Dmaven.cache.keyValueRefs=<bad> where <bad> is not soft/hard/weak/none in any case, e.g. 'sof t', 'softref', or an empty-but-nonblank string like a stray comma-separated list.

Common situations: Typos in MAVEN_OPTS or .mvn/maven.config; copying a value from documentation of a different cache system; shell quoting that mangles the value (e.g. -Dmaven.cache.keyValueRefs="soft" with invisible characters).

Related errors

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