{"record":{"id":"4e755baf94dbc3c3","repo":"charmbracelet/crush","slug":"timeout-waiting-for-agent-readiness","errorCode":null,"errorMessage":"timeout waiting for agent readiness","messagePattern":"timeout waiting for agent readiness","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cmd/run.go","lineNumber":471,"sourceCode":"\t}\n\treturn false, nil\n}\n\n// waitForAgent polls GetAgentInfo until the agent is ready, with a\n// timeout.\nfunc waitForAgent(ctx context.Context, c *client.Client, wsID string) error {\n\ttimeout := time.After(30 * time.Second)\n\tfor {\n\t\tinfo, err := c.GetAgentInfo(ctx, wsID)\n\t\tif err == nil && info.IsReady {\n\t\t\treturn nil\n\t\t}\n\t\tselect {\n\t\tcase <-timeout:\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"timeout waiting for agent: %w\", err)\n\t\t\t}\n\t\t\treturn fmt.Errorf(\"timeout waiting for agent readiness\")\n\t\tcase <-ctx.Done():\n\t\t\treturn ctx.Err()\n\t\tcase <-time.After(200 * time.Millisecond):\n\t\t}\n\t}\n}\n\n// overrideModels resolves model strings and updates the workspace\n// configuration via the server.\nfunc overrideModels(\n\tctx context.Context,\n\tc *client.Client,\n\tws *proto.Workspace,\n\tlargeModel, smallModel string,\n) error {\n\tcfg, err := c.GetConfig(ctx, ws.ID)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to get config: %w\", err)","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/charmbracelet/crush/blob/7944b8e52225d8805e31eacbf7ef24856b0dfb7a/internal/cmd/run.go#L453-L489","documentation":"Thrown by waitForAgent (internal/cmd/run.go:471) when the 30-second timeout elapses while the agent is still polling successfully but never reports IsReady=true. Unlike the sibling error at line 469, there is no underlying transport error; the server responds but the agent remains unready.","triggerScenarios":"c.GetAgentInfo(ctx, wsID) succeeds (err == nil) every 200ms for 30 seconds, but info.IsReady stays false the entire time; then the timeout channel fires and this error is returned.","commonSituations":"Agent stuck initializing (LSP or MCP server hang, provider catalog download blocked), server overloaded, agent in a permanent error/retry state server-side, or a stale agent process that will never become ready.","solutions":["Check server logs for the agent's initialization state to find why IsReady never flips to true","Verify MCP/LSP servers and provider configured in the workspace start correctly","Retry the command; if it recurs, restart the server/agent process","Increase the timeout if initialization is legitimately slow (cold cache, slow network)","Report a bug if the agent is permanently wedged despite healthy dependencies"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := runNonInteractive(...); err != nil {\n\tif err.Error() == \"timeout waiting for agent readiness\" {\n\t\t// poll GetAgentInfo yourself or restart the server, then retry once\n\t}\n}","preventionTips":["Check server/agent logs when readiness never flips","Ensure MCP/LSP servers configured for the workspace start correctly","Avoid running on hosts with blocked outbound network (provider catalog fetch)","Restart stale agent processes before scripted runs"],"tags":["timeout","startup","readiness","go"],"backgroundTag":"agent-startup-timeout","analyzedSha":"7944b8e52225d8805e31eacbf7ef24856b0dfb7a","analyzedAt":"2026-08-29T12:48:59.079Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}