{"record":{"id":"0e2639c8e72700bc","repo":"googleapis/mcp-toolbox","slug":"graceful-shutdown-timed-out-forcing-exit-0e2639","errorCode":null,"errorMessage":"graceful shutdown timed out... forcing exit","messagePattern":"graceful shutdown timed out\\.\\.\\. forcing exit","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cmd/root.go","lineNumber":530,"sourceCode":"\t\t// start watching the file(s) or folder for changes to trigger dynamic reloading\n\t\tgo watchChanges(ctx, watchDirs, watchedFiles, s, opts)\n\t}\n\n\t// wait for either the server to error out or the command's context to be canceled\n\tselect {\n\tcase err := <-srvErr:\n\t\tif err != nil {\n\t\t\terrMsg := fmt.Errorf(\"toolbox crashed with the following error: %w\", err)\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\tcase <-ctx.Done():\n\t\tshutdownContext, cancel := context.WithTimeout(context.Background(), 10*time.Second)\n\t\tdefer cancel()\n\t\topts.Logger.WarnContext(shutdownContext, \"Shutting down gracefully...\")\n\t\terr := s.Shutdown(shutdownContext)\n\t\tif err == context.DeadlineExceeded {\n\t\t\treturn fmt.Errorf(\"graceful shutdown timed out... forcing exit\")\n\t\t}\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":512,"sourceCodeEnd":536,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/root.go#L512-L536","documentation":"On SIGINT/SIGTERM (ctx.Done), toolbox calls s.Shutdown with a 10-second context. If Shutdown returns context.DeadlineExceeded, graceful shutdown did not finish in time, so run() returns this error indicating a forced exit with in-flight requests possibly dropped.","triggerScenarios":"Server shutdown exceeds 10s — typically long-lived connections (streaming MCP sessions, SSE, keep-alive HTTP connections) that prevent the server from draining.","commonSituations":"Kubernetes pod termination with open streaming connections; clients holding idle keep-alive connections; slow in-flight DB queries blocking request completion during shutdown.","solutions":["Ensure clients close streaming/keep-alive connections on shutdown signals","Reduce long-running queries or add server-side timeouts","Gracefully drain the load balancer before stopping the instance","If this recurs, investigate stuck connections during shutdown"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"// treat exit as shutdown-timeout and ensure cleanup\nif err := cmd.Wait(); err != nil {\n    log.Println(\"graceful shutdown timed out; forcing exit\")\n    // kill process group / release LB target before restart\n}","preventionTips":["Drain load balancers before terminating instances","Terminate long-lived streaming clients on SIGTERM","Keep DB queries under 10s or add request timeouts","Allow adequate terminationGracePeriodSeconds in k8s"],"tags":["shutdown","timeout","graceful"],"backgroundTag":"graceful-shutdown-timeout","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}