{"record":{"id":"ac158baab3a8dcd1","repo":"charmbracelet/crush","slug":"timeout-waiting-for-lsp-server-to-be-ready","errorCode":null,"errorMessage":"timeout waiting for LSP server to be ready","messagePattern":"timeout waiting for LSP server to be ready","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/lsp/client.go","lineNumber":362,"sourceCode":"func (c *Client) WaitForServerReady(ctx context.Context) error {\n\t// Set initial state\n\tc.SetServerState(StateStarting)\n\n\t// Try to ping the server with a simple request\n\tticker := time.NewTicker(500 * time.Millisecond)\n\tdefer ticker.Stop()\n\n\tif c.debug {\n\t\tslog.Debug(\"Waiting for LSP server to be ready...\")\n\t}\n\n\tc.openKeyConfigFiles(ctx)\n\n\tfor {\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\tc.SetServerState(StateError)\n\t\t\treturn fmt.Errorf(\"timeout waiting for LSP server to be ready\")\n\t\tcase <-ticker.C:\n\t\t\t// Check if client is running\n\t\t\tif !c.client.IsRunning() {\n\t\t\t\tif c.debug {\n\t\t\t\t\tslog.Debug(\"LSP server not ready yet\", \"server\", c.name)\n\t\t\t\t}\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\t// Server is ready\n\t\t\tc.SetServerState(StateReady)\n\t\t\tif c.debug {\n\t\t\t\tslog.Debug(\"LSP server is ready\")\n\t\t\t}\n\t\t\treturn nil\n\t\t}\n\t}\n}","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/charmbracelet/crush/blob/7944b8e52225d8805e31eacbf7ef24856b0dfb7a/internal/lsp/client.go#L344-L380","documentation":"WaitForServerReady polls the client (via ticker) until the LSP server reports running/ready, opening key config files meanwhile. If the context is cancelled or its deadline expires before the server becomes ready, the client is set to StateError and this fixed timeout message is returned. It means initialize may have completed but the server never signaled readiness.","triggerScenarios":"Calling Restart or startServer with a context whose deadline expires before the server reaches a ready state — slow first-time server startup (indexing), server stuck after initialize, or server process died and IsRunning() never becomes true.","commonSituations":"Large projects where the server takes minutes to index before ready; gopls/python-language-server cold start on limited hardware; server hung due to a bad config file it tries to load; deadline set shorter than realistic startup time.","solutions":["Increase the readiness timeout (context deadline) passed into WaitForServerReady.","Enable debug logging (c.debug) to observe polling and see if the server is progressing or dead.","Check the server's own logs to find why it never becomes ready.","Ensure the server process isn't crashing right after initialize (it would never report running).","Retry the restart once deadlocks/hangs are ruled out."],"exampleFix":"// before\nctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)\nready, err := client.WaitForServerReady(ctx)\n\n// after\nctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)\nready, err := client.WaitForServerReady(ctx)","handlingStrategy":"retry","validationCode":"// Poll cheaply before waiting on readiness\nticker := time.NewTicker(time.Second)\nif !client.IsRunning() {\n    return fmt.Errorf(\"lsp process already exited; check server logs before waiting for readiness\")\n}","typeGuard":"func isReadinessTimeout(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"timeout waiting for LSP server to be ready\")\n}","tryCatchPattern":"readyCtx, cancel := context.WithTimeout(ctx, 3*time.Minute)\ndefer cancel()\nif err := client.WaitForServerReady(readyCtx); err != nil {\n    if isReadinessTimeout(err) {\n        slog.Warn(\"LSP not ready in time; inspect server logs\", \"error\", err)\n    }\n    return err\n}","preventionTips":["Size the readiness timeout to the largest expected project, not the smallest.","Enable client debug logging to distinguish slow startup from a hung server.","Check for server processes stuck on corrupted caches and clear them periodically."],"tags":["lsp","timeout","server-startup"],"backgroundTag":"lsp-readiness-timeout","analyzedSha":"7944b8e52225d8805e31eacbf7ef24856b0dfb7a","analyzedAt":"2026-08-29T12:48:59.079Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}