What causes "Unknown reference type: {}, using default SOFT" in apache/maven?

Use one of the accepted reference values: soft, hard, weak, or none

Unknown reference type: {}, using default SOFT

Error message

Unknown reference type: {}, using default SOFT

What it means

The 'ref'/'reference' key of a cache selector configuration was parsed and its value (lower-cased) matched none of soft, hard, weak, or none. parseReferenceType() logs the value and yields the default Cache.ReferenceType.SOFT, so cache entries keep soft references even though a different strategy was requested. Behavior remains correct but memory/GC characteristics differ from the intent.

Source

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

            case "disabled", "none" -> CacheRetention.DISABLED;
            default -> {
                LOGGER.warn("Unknown cache scope: {}, using default REQUEST_SCOPED", value);
                yield CacheRetention.REQUEST_SCOPED;
            }
        };
    }

    /**
     * Parses a reference type string into Cache.ReferenceType.
     */
    private static Cache.ReferenceType parseReferenceType(String value) {
        return switch (value.toLowerCase(Locale.ENGLISH)) {
            case "soft" -> Cache.ReferenceType.SOFT;
            case "hard" -> Cache.ReferenceType.HARD;
            case "weak" -> Cache.ReferenceType.WEAK;
            case "none" -> Cache.ReferenceType.NONE;
            default -> {
                LOGGER.warn("Unknown reference type: {}, using default SOFT", value);
                yield Cache.ReferenceType.SOFT;
            }
        };
    }

    /**
     * Compares specificity of two selectors. More specific selectors should be checked first.
     * Specificity order: parent + request > request only > wildcard
     */
    private static int compareSpecificity(CacheSelector a, CacheSelector b) {
        int aScore = getSpecificityScore(a);
        int bScore = getSpecificityScore(b);
        return Integer.compare(aScore, bScore);
    }

    private static int getSpecificityScore(CacheSelector selector) {
        int score = 0;

View on GitHub (pinned to e4093d4e12)

Solutions

Use one of the accepted reference values: soft, hard, weak, or none
If you wanted entries pinned for the whole build, use reference=hard
Verify the whole selector string parses cleanly by checking that no cache-configuration warnings remain in the log

Example fix

# before
mvn clean install '-Dmaven.cache.config=**{scope=session,ref=strong}'

# after
mvn clean install '-Dmaven.cache.config=**{scope=session,ref=hard}'

Defensive patterns

Strategy: validation

Validate before calling

static final Set<String> VALID_REFS = Set.of("soft", "hard", "weak", "none");
String ref = kv.get("reference") != null ? kv.get("reference") : kv.get("ref");
if (ref != null && !VALID_REFS.contains(ref.trim().toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("reference must be soft|hard|weak|none, got: " + ref);
}

Type guard

Optional<Cache.ReferenceType> asRefType(String s) {
    if (s == null) return Optional.empty();
    return switch (s.trim().toLowerCase(Locale.ROOT)) {
        case "soft" -> Optional.of(Cache.ReferenceType.SOFT);
        case "hard" -> Optional.of(Cache.ReferenceType.HARD);
        case "weak" -> Optional.of(Cache.ReferenceType.WEAK);
        case "none" -> Optional.of(Cache.ReferenceType.NONE);
        default -> Optional.empty();
    };
}

Prevention

Use only soft/hard/weak/none; 'strong' and 'phantom' are not valid here
Keep the key (ref/reference) and value spelling in one reviewed config file
Assert no cache-configuration warnings appear in a canary build after config edits

When it happens

Trigger: -Dmaven.cache.config=<selector>{ref=<bad>} where <bad> is e.g. 'strong', 'string', 'ghost', or the enum name in the wrong case for an unsupported alias.

Common situations: GC terminology mix-ups (strong vs hard, phantom vs weak); autocompleted key names in editor configs; values valid for a different cache library pasted into maven.cache.config.

Related errors

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