{"record":{"id":"1c3013e54068e4ff","repo":"googleapis/mcp-toolbox","slug":"toolbox-crashed-with-the-following-error-w-1c3013","errorCode":null,"errorMessage":"toolbox crashed with the following error: %w","messagePattern":"toolbox crashed with the following error: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/root.go","lineNumber":520,"sourceCode":"\t\t\terr = s.Serve(ctx)\n\t\t\tif err != nil {\n\t\t\t\tsrvErr <- err\n\t\t\t}\n\t\t}()\n\t}\n\n\tif isCustomConfigured && !opts.Cfg.DisableReload {\n\t\twatchDirs, watchedFiles := resolveWatcherInputs(opts.Config, opts.Configs, opts.ConfigFolder)\n\n\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":502,"sourceCodeEnd":536,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/root.go#L502-L536","documentation":"When the server runs in a goroutine, runtime errors are sent to the srvErr channel. run() selects on srvErr and, if the server returned a non-nil error during serving (request handler panic surfacing, listener failure mid-run), wraps it as 'toolbox crashed with the following error'. The root cause is in the wrapped %w error.","triggerScenarios":"The running server goroutine sends a non-nil error to srvErr while handling traffic or while the listener breaks unexpectedly.","commonSituations":"Underlying port closed externally, TLS termination failure, or handler-level errors that escalate to the server loop in long-running deployments.","solutions":["Inspect the wrapped cause in the logs for the real failure","Restart the service and monitor for recurring crashes","Check host resource/port/TLS state at crash time","Upgrade to the latest toolbox release in case the crash is a known bug"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// supervise the toolbox process and react to crash\nif err := cmd.Run(); err != nil {\n    if strings.Contains(errString, \"toolbox crashed with the following error\") {\n        log.Printf(\"crash cause: %v; restarting with backoff\", err)\n        time.Sleep(backoff)\n        // retry with bounded attempts\n    }\n}","preventionTips":["Run under a supervisor (systemd/k8s) with restart policy and backoff","Monitor logs for the wrapped cause of each crash","Keep toolbox updated to benefit from crash fixes"],"tags":["runtime","server","crash"],"backgroundTag":"server-crash","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"}