alibaba/Sentinel · error · IllegalArgumentException

Invalid map instance

Error message

Invalid map instance

What it means

The second constructor of ConcurrentLinkedHashMapWrapper accepts a pre-built ConcurrentLinkedHashMap instance (used mainly in tests or when you supply your own map) and rejects null with IllegalArgumentException("Invalid map instance"). The wrapper delegates all CacheMap operations to the supplied map, so a null instance would break every subsequent operation.

Source

Thrown at sentinel-extension/sentinel-parameter-flow-control/src/main/java/com/alibaba/csp/sentinel/slots/statistic/cache/ConcurrentLinkedHashMapWrapper.java:48

    private static final int DEFAULT_CONCURRENCY_LEVEL = 16;

    private final ConcurrentLinkedHashMap<T, R> map;

    public ConcurrentLinkedHashMapWrapper(long size) {
        if (size <= 0) {
            throw new IllegalArgumentException("Cache max capacity should be positive: " + size);
        }
        this.map = new ConcurrentLinkedHashMap.Builder<T, R>()
            .concurrencyLevel(DEFAULT_CONCURRENCY_LEVEL)
            .maximumWeightedCapacity(size)
            .weigher(Weighers.singleton())
            .build();
    }

    public ConcurrentLinkedHashMapWrapper(ConcurrentLinkedHashMap<T, R> map) {
        if (map == null) {
            throw new IllegalArgumentException("Invalid map instance");
        }
        this.map = map;
    }

    @Override
    public boolean containsKey(T key) {
        return map.containsKey(key);
    }

    @Override
    public R get(T key) {
        return map.get(key);
    }

    @Override
    public R remove(T key) {
        return map.remove(key);
    }

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Construct the map before wrapping: new ConcurrentLinkedHashMapWrapper<>(new ConcurrentLinkedHashMap.Builder<T,R>().build())
2. Prefer the size-based constructor new ConcurrentLinkedHashMapWrapper<>(capacity) unless you specifically need a custom map
3. Add a null check / Objects.requireNonNull at the call site to fail with a clearer message

Example fix

// before
ConcurrentLinkedHashMap<T,R> map = maybeCreateMap(); // returns null on some path
wrapper = new ConcurrentLinkedHashMapWrapper<>(map);

// after
wrapper = new ConcurrentLinkedHashMapWrapper<>(
    new ConcurrentLinkedHashMap.Builder<T,R>().maximumWeightedCapacity(CAP).build());

ConcurrentLinkedHashMap<T,R> m = buildMap();
if (m == null) throw new IllegalStateException("map builder returned null");
wrapper = new ConcurrentLinkedHashMapWrapper<>(m);

private static boolean isWrappable(ConcurrentLinkedHashMap<?,?> m) {
    return m != null;
}

When it happens

Trigger: new ConcurrentLinkedHashMapWrapper<>(null), i.e. calling the delegate-map constructor with a null ConcurrentLinkedHashMap, typically in custom wiring or test setup where the map variable failed to initialize.

Common situations: Refactoring code that previously built the map inline into a constructor argument, leaving a null placeholder; conditional initialization where the branch that creates the map is skipped; copy-pasted test scaffolding.

Related errors

• Cache max capacity should be positive: ${size}
• ${name} is null
• Null method
• Request cannot be null
• Bad class metadata

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/f85ff9572c79392d. Report an issue: GitHub.