sebastianbergmann/phpunit · error · ReturnValueNotConfiguredException

No return value is configured for %s::%s() and return value

Error message

No return value is configured for %s::%s() and return value generation is disabled

What it means

Thrown by InvocationHandler::invoke() when a method call on the double matched no expectation and return value generation is disabled, so PHPUnit has nothing to return. Mock objects (createMock / expects()) run with returnValueGeneration=false: every method that production code actually calls must be covered by a matching expectation with a will(...) action, or the test fails here instead of returning a silent default. __toString is the single special case and returns '' instead of throwing.

Source

Thrown at src/Framework/MockObject/Runtime/InvocationHandler.php:184

                    $this->assertionFailure = $e;
                }
            }
        }

        if ($exception !== null) {
            throw $exception;
        }

        if ($hasReturnValue) {
            return $returnValue;
        }

        if (!$this->returnValueGeneration) {
            if (strtolower($invocation->methodName()) === '__tostring') {
                return '';
            }

            throw new ReturnValueNotConfiguredException($invocation);
        }

        return $invocation->generateReturnValue();
    }

    /**
     * @throws Throwable
     */
    public function verify(): void
    {
        foreach ($this->matchers as $matcher) {
            $matcher->verify();
        }

        if ($this->assertionFailure !== null) {
            throw $this->assertionFailure;
        }
    }

View on GitHub (pinned to f123cdb2a2)

Solutions

Add a matching expectation with a return value: $mock->method('helper')->willReturn(...).
If the arguments of the real call differ from your with() constraints, correct the constraints or use ->withAnyParameters().
If you only need indifferent default returns, use $this->createStub(C::class) instead of a mock with expects().
For mocks created via getMockBuilder(), avoid disabling return value generation, or use autoConfigure... i.e. configure returns for every method the subject calls.

Example fix

// before
$repo = $this->createMock(UserRepo::class);
$service->run($repo); // run() internally calls findAll(), unconfigured

// after
$repo = $this->createMock(UserRepo::class);
$repo->method('findAll')->willReturn([]);
$service->run($repo);

Defensive patterns

Strategy: fallback

Validate before calling

// before exercising the subject, enumerate every collaborator method it calls and stub it
foreach (['findAll', 'find', 'save'] as $method) {
    $repo->method($method)->willReturn($defaults[$method] ?? null);
}

Type guard

// no language-level guard; instead choose the right factory:
// createStub() enables return value generation, createMock() disables it
function doubleWithDefaults(string $class): Stub
{
    return PHPUnit\Framework\TestCase::createStub($class); // safe default returns
}

Try / catch

try {
    $subject->run($mock);
} catch (PHPUnit\Framework\MockObject\ReturnValueNotConfiguredException $e) {
    // read which method was called, add ->method(...)->willReturn(...), rerun
}

Prevention

Use createStub() when you only need indifferent return values; use createMock() only when asserting calls.
When an expectation exists but the call still throws, suspect with() constraints that do not match the real arguments.
Read the exception — it names the exact class::method that lacked a return value.

When it happens

Trigger: Production code under test calls $mock->helper() while the test only configured ->method('other'); an expectation exists for helper() but its with()/parameter rule does not match the actual arguments, so no matcher applies; calling any method on a mock created with createMock() without configuring a return for it.

Common situations: Exercising more of the subject than the test author realized (helper/format/log methods called in passing); using a mock where a stub was intended — createStub() enables generation and returns defaults; refactoring production code so previously untested methods are now called on the mock.

Related errors

AI-assisted analysis of sebastianbergmann/phpunit@f123cdb2a2 (2026-08-23). Data as JSON: /api/errors/2c9a6a89b00112db. Report an issue: GitHub.