mockito/mockito · error · InvalidUseOfMatchersException

No matchers found for additional matcher ${additionalMatcher

Error message

No matchers found for additional matcher ${additionalMatcherName}
${location}

What it means

Thrown by ArgumentMatcherStorageImpl.assertStateFor when AdditionalMatchers.and()/or()/not() is reported but the matcher stack is empty — i.e. no sub-matchers were registered before the combinator was applied. The additional matcher requires at least one (and the requested number of) sub-matchers on the stack.

Source

Thrown at mockito-core/src/main/java/org/mockito/internal/progress/ArgumentMatcherStorageImpl.java:85

        reportMatcher(new Not(m));
    }

    @Override
    public void validateState() {
        if (!matcherStack.isEmpty()) {
            List<LocalizedMatcher> lastMatchers = resetStack();
            throw misplacedArgumentMatcher(lastMatchers);
        }
    }

    @Override
    public void reset() {
        matcherStack.clear();
    }

    private void assertStateFor(String additionalMatcherName, int subMatchersCount) {
        if (matcherStack.isEmpty()) {
            throw reportNoSubMatchersFound(additionalMatcherName);
        }
        if (matcherStack.size() < subMatchersCount) {
            List<LocalizedMatcher> lastMatchers = resetStack();
            throw incorrectUseOfAdditionalMatchers(
                    additionalMatcherName, subMatchersCount, lastMatchers);
        }
    }

    private ArgumentMatcher<?> popMatcher() {
        return matcherStack.pop().getMatcher();
    }

    private List<LocalizedMatcher> resetStack() {
        ArrayList<LocalizedMatcher> lastMatchers = new ArrayList<>(matcherStack);
        reset();
        return lastMatchers;
    }
}

View on GitHub (pinned to 5a676bcd9e)

Solutions

1. Provide the required sub-matchers inside the combinator, e.g. AdditionalMatchers.and(gt(0), lt(10))
2. Use the combinator only within when(...) or verify(...)
3. Check that inner matcher calls were not accidentally deleted or commented out

Example fix

// before
verify(mock).foo(AdditionalMatchers.and());
// after
verify(mock).foo(AdditionalMatchers.and(gt(0), lt(10)));

// Ensure AdditionalMatchers combinators always receive sub-matchers
if (subMatcherCount == 0) {
    throw new IllegalArgumentException("AdditionalMatchers.and/or/not require sub-matchers");
}

When it happens

Trigger: Calling AdditionalMatchers.not() / and() / or() without any matcher arguments registered, e.g. AdditionalMatchers.and() with zero matchers, or calling these outside of when/verify so matchers were never pushed.

Common situations: Typos dropping the inner matcher call; using AdditionalMatchers in plain code outside stubbing/verification; refactoring removed the inner any()/eq() calls but left the combinator.

Related errors

• Invalid use of argument matchers inside additional matcher $
• Invalid use of argument matchers! ${expectedCount} matchers
• Misplaced or misused argument matcher detected here: ${locat
• Unable to create mock instance of type '<typeSimpleName>'
• Arrays cannot be mocked: <typeToMock>.

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