{"record":{"id":"9930ed490eb6af87","repo":"symfony/http-kernel","slug":"the-controller-must-return-a-symfony-component","errorCode":null,"errorMessage":"The controller must return a \"Symfony\\Component\\HttpFoundation\\Response\" object but it returned %s. Did you forget to add a return statement somewhere in your controller?","messagePattern":"The controller must return a \"Symfony\\\\Component\\\\HttpFoundation\\\\Response\" object but it returned (.+?)\\. Did you forget to add a return statement somewhere in your controller\\?","errorType":"exception","errorClass":"ControllerDoesNotReturnResponseException","httpStatus":null,"severity":"error","filePath":"HttpKernel.php","lineNumber":205,"sourceCode":"        // call controller\n        $response = $controller(...$arguments);\n\n        // view\n        if (!$response instanceof Response) {\n            $event = new ViewEvent($this, $request, $type, $response, $controllerMetadata);\n            $this->dispatcher->dispatch($event, KernelEvents::VIEW);\n\n            if ($event->hasResponse()) {\n                $response = $event->getResponse();\n            } else {\n                $msg = \\sprintf('The controller must return a \"Symfony\\Component\\HttpFoundation\\Response\" object but it returned %s.', $this->varToString($response));\n\n                // the user may have forgotten to return something\n                if (null === $response) {\n                    $msg .= ' Did you forget to add a return statement somewhere in your controller?';\n                }\n\n                throw new ControllerDoesNotReturnResponseException($msg, $controller, __FILE__, __LINE__ - 17);\n            }\n        }\n\n        return $this->filterResponse($response, $request, $type, $controllerMetadata);\n    }\n\n    /**\n     * Filters a response object.\n     *\n     * @throws \\RuntimeException if the passed object is not a Response instance\n     */\n    private function filterResponse(Response $response, Request $request, int $type, ?ControllerMetadata $controllerMetadata = null): Response\n    {\n        $event = new ResponseEvent($this, $request, $type, $response, $controllerMetadata instanceof ControllerArgumentsMetadata ? $controllerMetadata : null);\n\n        $this->dispatcher->dispatch($event, KernelEvents::RESPONSE);\n\n        $this->finishRequest($request, $type, $controllerMetadata);","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/symfony/http-kernel/blob/aa3a39d7286a62cdfea98f0e69c651a3da6e36cf/HttpKernel.php#L187-L223","documentation":"The kernel requires every controller to return a Symfony Response object (or null when allowNull is set, which then also triggers this exception if a response is mandatory). If the controller returns any other type, ControllerDoesNotReturnResponseException is thrown with this message, hinting at a forgotten return statement.","triggerScenarios":"A controller returns null, a string, an array, or a non-Response object while the kernel still requires a Response (no view event produced one and null is not allowed).","commonSituations":"Forgot `return` before `$this->json(...)`; controller returns an array without the serializer view listener handling it; returning void by accident; refactoring that changed the return type.","solutions":["Add a return statement so the controller returns a Response","Wrap non-Response results: new JsonResponse($data) or $this->json($data)","If returning null intentionally, ensure the kernel/view event converts it (or allow null return type semantics)","Add a controller return type declaration (Response) so static analysis catches it"],"exampleFix":"// before\npublic function index(): JsonResponse\n{\n    $this->json(['ok' => true]);\n}\n\n// after\npublic function index(): JsonResponse\n{\n    return $this->json(['ok' => true]);\n}","handlingStrategy":"type-guard","validationCode":"// static analysis: enforce return types\n// /** @return Response */ and run PHPStan/Psalm level that flags missing returns","typeGuard":"function assertResponse(mixed $result): \\Symfony\\Component\\HttpFoundation\\Response {\n    if (!$result instanceof \\Symfony\\Component\\HttpFoundation\\Response) {\n        throw new \\TypeError('Controller must return a Response, got '.get_debug_type($result));\n    }\n    return $result;\n}","tryCatchPattern":"try { $response = $kernel->handle($request); } catch (ControllerDoesNotReturnResponseException $e) { /* points at offending controller file:line */ }","preventionTips":["Declare Response (or JsonResponse) return types on all controllers","Never rely on returning plain arrays without a view/serializer listener","Run PHPStan/Psalm with missing-return checks in CI","Grep for controllers without `return` before building the response"],"tags":["http-kernel","controller","response","return-type"],"backgroundTag":"type-mismatch","analyzedSha":"aa3a39d7286a62cdfea98f0e69c651a3da6e36cf","analyzedAt":"2026-09-13T18:03:36.509Z","contentChangedAt":"2026-09-13T18:03:36.509Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}