{"record":{"id":"b37adf6c8918d00b","repo":"laravel/framework","slug":"service-unavailable","errorCode":null,"errorMessage":"Service Unavailable","messagePattern":"Service Unavailable","errorType":"http","errorClass":"HttpException","httpStatus":503,"severity":"error","filePath":"src/Illuminate/Foundation/Http/Middleware/PreventRequestsDuringMaintenance.php","lineNumber":101,"sourceCode":"            if (isset($data['redirect']) && ! $request->expectsJson()) {\n                $path = $data['redirect'] === '/'\n                    ? $data['redirect']\n                    : trim($data['redirect'], '/');\n\n                if ($request->path() !== $path) {\n                    return redirect($path);\n                }\n            }\n\n            if (isset($data['template']) && ! $request->expectsJson()) {\n                return response(\n                    $data['template'],\n                    $data['status'] ?? 503,\n                    $this->getHeaders($data)\n                );\n            }\n\n            throw new HttpException(\n                $data['status'] ?? 503,\n                'Service Unavailable',\n                null,\n                $this->getHeaders($data)\n            );\n        }\n\n        return $next($request);\n    }\n\n    /**\n     * Determine if the incoming request has a maintenance mode bypass cookie.\n     *\n     * @param  \\Illuminate\\Http\\Request  $request\n     * @param  array  $data\n     * @return bool\n     */\n    protected function hasValidBypassCookie($request, array $data)","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/laravel/framework/blob/deac04fbdcd7443aff45a7bc6767a6729169bba3/src/Illuminate/Foundation/Http/Middleware/PreventRequestsDuringMaintenance.php#L83-L119","documentation":"Thrown as an HttpException (default status 503) by PreventRequestsDuringMaintenance when the app's maintenance mode is active, the request carries no valid bypass cookie/secret, and the maintenance data has no 'template' or 'redirect' key to render instead. It is the fallback 'down for maintenance' response.","triggerScenarios":"Running php artisan down and then hitting any non-excluded route without the bypass cookie; the maintenance payload containing only status/retry without a template; a request that does not match the secret bypass path and lacks the laravel_maintenance cookie.","commonSituations":"Forgot to take the app out of maintenance (php artisan up) after a deploy; custom maintenance payload that omits 'template'; deploy scripts that run down but fail before up; CI hitting the app during a maintenance window.","solutions":["Run php artisan up to disable maintenance mode.","Provide a maintenance template via php artisan down --render='errors::503' (or a custom view) so a page renders instead of a bare exception.","Add critical paths to PreventRequestsDuringMaintenance::except() so health checks/API still work.","Use php artisan down --secret=... and visit the secret URL to obtain the bypass cookie for testing during downtime."],"exampleFix":"// before\nphp artisan down  // bare maintenance, no template -> HttpException 503\n\n// after\nphp artisan down --render='errors::maintenance' --retry=60\nphp artisan up  // when deploy complete","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    $response = $kernel->handle($request);\n} catch (\\Symfony\\Component\\HttpKernel\\Exception\\HttpException $e) {\n    if ($e->getStatusCode() === 503) {\n        return response()->json(['message' => 'Maintenance in progress.', 'retry' => $e->getHeaders()['Retry-After'] ?? null], 503);\n    }\n    throw $e;\n}","preventionTips":["Always run php artisan up after deploys (automate it in your deploy script).","Render a maintenance template so users see a page, not a bare exception.","Exclude health-check and status endpoints via PreventRequestsDuringMaintenance::except().","Use a maintenance secret for safe testing during downtime."],"tags":["maintenance","deployment","http-exception"],"analyzedSha":"deac04fbdcd7443aff45a7bc6767a6729169bba3","analyzedAt":"2026-08-06T23:23:39.652Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}