OpenFeign/feign · error · VerificationAssertionError

Received excessive request

Error message

Received excessive request %s

What it means

MockClient in sequential mode throws VerificationAssertionError("Received excessive request %s") when more requests arrive than were queued: the response iterator is exhausted but the client under test issues another call. It means the mock was set up with fewer stubbed responses than actual invocations.

Solutions

1. Add a stubbed response for every expected call via mockClient.add(...) in order
2. Ensure the test code makes exactly as many calls as stubbed
3. Disable unexpected retries with Retryer.NEVER_RETRY in the Feign builder
4. Call mockClient.verifyStatus()/verifyResults() in tests to catch mismatches early

Example fix

// before
mockClient.add(okResponse);
api.call(); api.call(); // excessive request
// after
mockClient.add(okResponse);
mockClient.add(secondResponse);
api.call(); api.call();

// assert stub count matches expected call count before running the test
// assertEquals(expectedCalls, mockClient.getResponsesCount()); // or count added stubs in setup

try { runScenario(); }
catch (VerificationAssertionError e) {
  if (e.getMessage().startsWith("Received excessive request")) throw new AssertionError("Add a stub for every call or disable retries: " + e.getMessage(), e);
  throw e;
}

When it happens

Trigger: Using MockClient with sequential behavior (e.g. mockClient.add(response) once) while the code under test calls the Feign method twice, or retries issuing extra HTTP calls.

Common situations: Adding retries (e.g. Retryer.NEVER_RETRY not set) causing duplicate calls; loops making more calls than stubbed; forgetting to add a response for each expected call in a sequence.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• times must be a non negative number
• Wanted: ' ' but never invoked! Got
• Wanted: ' ' to be invoked: ' ' times but got: ' '!
• Do not wanted: ' ' but was invoked!
• Status Code [ ] has already been declared to throw [ ] and…

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/d00a34a2a78d7bb1. Report an issue: GitHub.

Appendix: source

Thrown at mock/src/main/java/feign/mock/MockClient.java:92

    RequestKey requestKey = RequestKey.create(request);
    Response.Builder responseBuilder;
    if (sequential) {
      responseBuilder = executeSequential(requestKey);
    } else {
      responseBuilder = executeAny(request, requestKey);
    }
    responseBuilder.protocolVersion(ProtocolVersion.MOCK);

    return CompletableFuture.completedFuture(responseBuilder.request(request).build());
  }

  private Response.Builder executeSequential(RequestKey requestKey) {
    Response.Builder responseBuilder;
    if (responseIterator == null) {
      responseIterator = responses.iterator();
    }
    if (!responseIterator.hasNext()) {
      throw new VerificationAssertionError("Received excessive request %s", requestKey);
    }

    RequestResponse expectedRequestResponse = responseIterator.next();
    if (!expectedRequestResponse.requestKey.equalsExtended(requestKey)) {
      throw new VerificationAssertionError(
          "Expected: \n%s,\nbut was: \n%s", expectedRequestResponse.requestKey, requestKey);
    }

    responseBuilder = expectedRequestResponse.responseBuilder;
    return responseBuilder;
  }

  private Response.Builder executeAny(Request request, RequestKey requestKey) {
    Response.Builder responseBuilder;
    if (requests.containsKey(requestKey)) {
      requests.get(requestKey).add(request);
    } else {
      requests.put(requestKey, new ArrayList<>(Arrays.asList(request)));

View on GitHub (pinned to e2a1e27560)