{"record":{"id":"32e71f8716ce8143","repo":"charmbracelet/crush","slug":"lost-connection-to-the-crush-server","errorCode":null,"errorMessage":"lost connection to the crush server","messagePattern":"lost connection to the crush server","errorType":"exception","errorClass":"ErrServerUnreachable","httpStatus":null,"severity":"error","filePath":"internal/workspace/workspace.go","lineNumber":38,"sourceCode":"\t\"github.com/charmbracelet/crush/internal/oauth\"\n\t\"github.com/charmbracelet/crush/internal/permission\"\n\t\"github.com/charmbracelet/crush/internal/proto\"\n\t\"github.com/charmbracelet/crush/internal/question\"\n\t\"github.com/charmbracelet/crush/internal/session\"\n\t\"github.com/charmbracelet/crush/internal/skills\"\n)\n\n// Reasons the coder agent may be unavailable, returned by\n// Workspace.AgentReadyErr so callers can tell a genuinely\n// uninitialized agent apart from a lost server connection.\nvar (\n\t// ErrAgentNotInitialized means the workspace exists but its coder\n\t// agent has not been configured/initialized (e.g. no model set).\n\tErrAgentNotInitialized = errors.New(\"coder agent is not initialized\")\n\t// ErrServerUnreachable means the client could not reach the server\n\t// to determine the agent's status (server down, or the workspace was\n\t// torn down out from under the client).\n\tErrServerUnreachable = errors.New(\"lost connection to the crush server\")\n\t// ErrWorkspaceGone means the server is reachable but no longer knows\n\t// this client's workspace: it was torn down, or the server was\n\t// replaced underneath the client. The subscription loop re-registers\n\t// the workspace in the background when it sees this.\n\tErrWorkspaceGone = errors.New(\"the server reset this workspace; reconnecting\")\n\t// ErrStreamClosed means an established event stream ended.\n\t// Resubscribing usually succeeds immediately, but events published in\n\t// the meantime are lost for good, so the client treats it as a\n\t// degraded link that requires a resync.\n\tErrStreamClosed = errors.New(\"the event stream closed; reconnecting\")\n)\n\n// ConnectionState describes the health of the client-server link as\n// reported by the [ClientWorkspace] subscription loop.\ntype ConnectionState int\n\nconst (\n\t// ConnectionDegraded means the event stream is down (or the workspace","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/charmbracelet/crush/blob/7944b8e52225d8805e31eacbf7ef24856b0dfb7a/internal/workspace/workspace.go#L20-L56","documentation":"ErrServerUnreachable is a sentinel error meaning the client could not reach the crush server to determine the agent's status — either the server is down or the workspace was torn down out from under the client. It is returned by AgentReadyErr so callers can distinguish connectivity loss from an uninitialized agent.","triggerScenarios":"AgentReadyErr called while the server process is down or restarting; the workspace the client holds was torn down server-side so status queries fail at the transport level.","commonSituations":"Server crashed or was killed mid-session; network drop between client and server; server redeploy removed the workspace the client cached.","solutions":["Restart or reconnect to the crush server and verify it is listening","Retry AgentReadyErr with backoff; treat it as transient connectivity loss","Re-create the workspace/client if the server was permanently replaced"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// probe before use\nif err := ws.AgentReadyErr(ctx); errors.Is(err, workspace.ErrServerUnreachable) {\n    // defer or queue the request\n}","typeGuard":"func isServerUnreachable(err error) bool { return errors.Is(err, workspace.ErrServerUnreachable) }","tryCatchPattern":"if err != nil {\n    if errors.Is(err, workspace.ErrServerUnreachable) {\n        return retryWithBackoff(ctx, op)\n    }\n    return err\n}","preventionTips":["Run the crush server under a supervisor (systemd) so it auto-restarts","Use exponential backoff for AgentReadyErr/SendMessage retries","Monitor server liveness from the client before batching work"],"tags":["network","connectivity","sentinel-error"],"backgroundTag":"server-unreachable","analyzedSha":"7944b8e52225d8805e31eacbf7ef24856b0dfb7a","analyzedAt":"2026-08-29T12:48:59.079Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}