{"id":"295a3bcb29f14487","repo":"gofiber/fiber","slug":"shutdown-graceful-timeout-has-been-reached-exiti","errorCode":null,"errorMessage":"shutdown: graceful timeout has been reached, exiting","messagePattern":"shutdown: graceful timeout has been reached, exiting","errorType":"exception","errorClass":"ErrGracefulTimeout","httpStatus":null,"severity":"warning","filePath":"error.go","lineNumber":16,"sourceCode":"package fiber\n\nimport (\n\t\"encoding/json\"\n\t\"errors\"\n\n\t\"github.com/gofiber/schema\"\n)\n\n// Wrap and return this for unreachable code if panicking is undesirable (i.e., in a handler).\n// Unexported because users will hopefully never need to see it.\nvar errUnreachable = errors.New(\"fiber: unreachable code, please create an issue at github.com/gofiber/fiber\")\n\n// General errors\nvar (\n\tErrGracefulTimeout = errors.New(\"shutdown: graceful timeout has been reached, exiting\")\n\t// ErrNotRunning indicates that a Shutdown method was called when the server was not running.\n\tErrNotRunning = errors.New(\"shutdown: server is not running\")\n\t// ErrHandlerExited is returned by App.Test if a handler panics or calls runtime.Goexit().\n\tErrHandlerExited = errors.New(\"runtime.Goexit() called in handler or server panic\")\n\t// ErrNoViewEngineConfigured indicates that a helper requiring a view engine was invoked without one configured.\n\tErrNoViewEngineConfigured = errors.New(\"fiber: no view engine configured\")\n\t// ErrAutoCertWithCertFile indicates AutoCertManager cannot be used with CertFile/CertKeyFile.\n\tErrAutoCertWithCertFile = errors.New(\"tls: AutoCertManager cannot be combined with CertFile/CertKeyFile\")\n)\n\n// Fiber redirection errors\nvar (\n\tErrRedirectBackNoFallback = NewError(StatusInternalServerError, \"Referer not found, you have to enter fallback URL for redirection.\")\n)\n\n// Range errors\nvar (\n\t// ErrRangeMalformed is returned for a syntactically invalid Range header,","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/gofiber/fiber/blob/9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c/error.go#L1-L34","documentation":"ErrGracefulTimeout (error.go:16) is the sentinel returned by Fiber's shutdown path when the graceful shutdown window expires before all in-flight connections reach idle. It is the user-facing signal that ShutdownWithTimeout / ShutdownWithContext hit the deadline and the server is exiting, rather than waiting indefinitely. Callers typically branch on it to decide whether to log a warning or proceed with forced cleanup.","triggerScenarios":"Calling app.ShutdownWithTimeout(d) or app.ShutdownWithContext(ctx) while long-lived or keep-alive connections are still open and the deadline (d / ctx deadline) elapses first. Slow streaming handlers or stuck WebSocket loops are the usual cause.","commonSituations":"Production SIGTERM handling where ReadTimeout is 0 (keep-alive connections never close), handlers blocking on downstream services, or a shutdown timeout that is shorter than the slowest acceptable request. Deploying behind a load balancer that drains connections slowly also surfaces it.","solutions":["Increase the shutdown timeout so it exceeds your longest acceptable request duration.","Set a non-zero ReadTimeout / IdleTimeout so keep-alive connections are reaped during shutdown.","Ensure handlers respect the request context and abort on ctx.Done() instead of blocking indefinitely.","Treat this error as non-fatal in your shutdown handler: log it and continue exiting, since the server is already stopping."],"exampleFix":"// before\nif err := app.ShutdownWithTimeout(1 * time.Second); err != nil {\n    log.Fatal(err)\n}\n\n// after\nif err := app.ShutdownWithTimeout(30 * time.Second); err != nil {\n    if errors.Is(err, fiber.ErrGracefulTimeout) {\n        log.Printf(\"graceful shutdown timed out, forcing exit\")\n    } else {\n        log.Printf(\"shutdown error: %v\", err)\n    }\n}","handlingStrategy":"try-catch","validationCode":"// Ensure the shutdown timeout exceeds your slowest handler.\nmaxRequest := 30 * time.Second\nif shutdownTimeout < maxRequest {\n    shutdownTimeout = maxRequest + 5*time.Second\n}","typeGuard":null,"tryCatchPattern":"if err := app.ShutdownWithTimeout(timeout); err != nil {\n    if errors.Is(err, fiber.ErrGracefulTimeout) {\n        log.Printf(\"graceful timeout reached, forcing exit\")\n    } else if !errors.Is(err, fiber.ErrNotRunning) {\n        log.Printf(\"shutdown error: %v\", err)\n    }\n}","preventionTips":["Set a non-zero ReadTimeout/IdleTimeout so keep-alive connections drain during shutdown.","Make handlers respect ctx.Done() so they abort promptly on shutdown.","Treat ErrGracefulTimeout as informational, not fatal, in signal handlers."],"tags":["shutdown","server","lifecycle","fiber"],"analyzedSha":"9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c","analyzedAt":"2026-08-04T21:44:03.395Z","schemaVersion":2}