mockito/mockito · error · MockitoException

It is not possible to create a singleton mock of ConcurrentH

Error message

It is not possible to create a singleton mock of ConcurrentHashMap to avoid infinite loops within Mockito's implementation of mock handling

What it means

A singleton mock instruments the instance's class so all calls on that specific instance are intercepted. Because Mockito's own mock handling uses ConcurrentHashMap internally, making a ConcurrentHashMap instance a singleton mock would cause Mockito to intercept its own internal operations and loop infinitely. createSingletonMock rejects instances of ConcurrentHashMap with a MockitoException.

Source

Thrown at mockito-core/src/main/java/org/mockito/internal/creation/bytebuddy/InlineDelegateByteBuddyMockMaker.java:691

        Map<Class<?>, BiConsumer<Object, MockedConstruction.Context>> interceptors =
                mockedConstruction.get();
        if (interceptors == null) {
            interceptors = new WeakHashMap<>();
            mockedConstruction.set(interceptors);
        }
        mockedConstruction.getBackingMap().expungeStaleEntries();

        return new InlineConstructionMockControl<>(
                type, settingsFactory, handlerFactory, mockInitializer, interceptors);
    }

    @Override
    @SuppressWarnings("unchecked")
    public <T> SingletonMockControl<T> createSingletonMock(
            T instance, MockCreationSettings<T> settings, MockHandler<T> handler) {
        if (instance.getClass() == ConcurrentHashMap.class) {
            throw new MockitoException(
                    "It is not possible to create a singleton mock of ConcurrentHashMap "
                            + "to avoid infinite loops within Mockito's implementation of mock handling");
        }

        // Instrument the class
        createMockType(settings);

        Map<Object, MockMethodInterceptor> singletons = mockedSingletons.get();
        if (singletons == null) {
            singletons = new WeakIdentityMap<>();
            mockedSingletons.set(singletons);
        }
        mockedSingletons.getBackingMap().expungeStaleEntries();

        return new InlineSingletonMockControl<>(instance, singletons, settings, handler);
    }

    @Override

View on GitHub (pinned to 5a676bcd9e)

Solutions

  1. Wrap the ConcurrentHashMap behind your own interface/class and singleton-mock the wrapper
  2. Pass a different, mockable instance; only ConcurrentHashMap itself is excluded
  3. Refactor the code under test to accept an injectable Map abstraction
  4. Use a real ConcurrentHashMap and adjust test expectations instead of instrumentation

Example fix

// before
ConcurrentHashMap<String,String> map = new ConcurrentHashMap<>();
Mockito.mockSingleton(map); // throws
// after
interface SharedMap { String get(String k); }
class ConcurrentSharedMap implements SharedMap { ... }
SharedMap m = Mockito.mockSingleton(new ConcurrentSharedMap()); // mock the wrapper type
Defensive patterns

Strategy: validation

Validate before calling

static void assertSingletonMockable(Object instance) {
    if (instance.getClass() == java.util.concurrent.ConcurrentHashMap.class) {
        throw new IllegalArgumentException("Cannot singleton-mock ConcurrentHashMap instances");
    }
}
// before mockSingleton: assertSingletonMockable(instance);

Type guard

static boolean canSingletonMock(Object instance) {
    return instance != null && instance.getClass() != java.util.concurrent.ConcurrentHashMap.class;
}

Try / catch

try {
    control = Mockito.mockSingleton(chmInstance);
} catch (org.mockito.exceptions.base.MockitoException e) {
    if (e.getMessage().contains("ConcurrentHashMap")) {
        // wrap the map behind an interface and mock the wrapper
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Calling Mockito.mockSingleton(instance) (singleton-mock API) where the instance's runtime class is exactly ConcurrentHashMap, or passing such an instance through a generic helper.

Common situations: Test helpers that singleton-mock whatever instance a test provides; attempting to stub behavior of a shared concurrent map instance in legacy code.

Related errors

AI-assisted analysis of mockito/mockito@5a676bcd9e (2026-09-05). Data as JSON: /api/errors/cd9c15a0d4cec9c3. Report an issue: GitHub.