{"record":{"id":"2bdf5758d26f41af","repo":"sebastianbergmann/phpunit","slug":"method-s-s-is-declared-to-never-return","errorCode":null,"errorMessage":"Method %s::%s() is declared to never return","messagePattern":"Method (.+?)::(.+?)\\(\\) is declared to never return","errorType":"exception","errorClass":"NeverReturningMethodException","httpStatus":null,"severity":"error","filePath":"src/Framework/MockObject/Runtime/Invocation.php","lineNumber":102,"sourceCode":"    {\n        return $this->methodName;\n    }\n\n    /**\n     * @return array<mixed>\n     */\n    public function parameters(): array\n    {\n        return $this->parameters;\n    }\n\n    /**\n     * @throws Exception\n     */\n    public function generateReturnValue(): mixed\n    {\n        if ($this->returnType === 'never') {\n            throw new NeverReturningMethodException(\n                $this->className,\n                $this->methodName,\n            );\n        }\n\n        if ($this->isReturnTypeNullable) {\n            return null;\n        }\n\n        return (new ReturnValueGenerator)->generate(\n            $this->className,\n            $this->methodName,\n            $this->object,\n            $this->returnType,\n        );\n    }\n\n    public function toString(): string","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/sebastianbergmann/phpunit/blob/f123cdb2a2d49f15025794166cfed8bda8627dd2/src/Framework/MockObject/Runtime/Invocation.php#L84-L120","documentation":"Thrown by Invocation::generateReturnValue() when a method whose declared return type is 'never' is actually invoked on a double and no explicit stub action produced a return before this point. PHP semantics say a never-returning method must throw or exit; PHPUnit turns the attempt to fabricate a default return value into this explicit exception naming the class and method.","triggerScenarios":"The code under test calls a never-typed method on a mock/stub (e.g. a fatal-fail() helper declared : never) and the expectation has no will(...)/willReturnCallback(...) that throws; a generic fallback in InvocationHandler reaches generateReturnValue() for that invocation.","commonSituations":"Domain libraries declaring fail()/abort()/mustNotExist() helpers as : never; value objects with invariant guards; tests stubbing such helpers with expects($this->once()) only, then production code actually reaching the failure path; upgrading a dependency that changed a void helper to never.","solutions":["Make the expectation explicit that the call ends the flow: ->will($this->throwException(new \\LogicException('should not happen'))).","If the call is legitimate in the tested path, refactor the code under test so the never-method is not relied upon to return.","If you expect the method not to be called, keep expects($this->never()) and fix the production code that reaches it."],"exampleFix":"// before\n$guard = $this->createStub(Guard::class);\n$guard->method('abort'); // abort(): never — no action configured\n\n// after\n$guard = $this->createStub(Guard::class);\n$guard->method('abort')\n    ->will($this->throwException(new \\RuntimeException('aborted')));","handlingStrategy":"validation","validationCode":"$rm = new ReflectionMethod(Guard::class, 'abort');\nif ((string) $rm->getReturnType() === 'never') {\n    // never rely on default return generation for this method\n    $stub->method('abort')->will($this->throwException(new \\RuntimeException('abort')));\n}","typeGuard":"function isNeverReturning(ReflectionMethod $m): bool\n{\n    return (string) $m->getReturnType() === 'never';\n}","tryCatchPattern":"try {\n    $subject->run($stub);\n} catch (PHPUnit\\Framework\\MockObject\\NeverReturningMethodException $e) {\n    // the code reached a path that calls a never-method — treat as control flow\n}","preventionTips":["Audit stubbed APIs for : never methods (fail/abort helpers) and always attach a throwing stub action.","Model never-methods with ->will($this->throwException(...)), never with default generation.","Track upstream changes from void to never in dependencies you stub."],"tags":["phpunit","mock-object","never-return-type","return-value-generation","php-81"],"backgroundTag":"never-return-type-violation","analyzedSha":"f123cdb2a2d49f15025794166cfed8bda8627dd2","analyzedAt":"2026-08-23T01:20:58.058Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}