{"record":{"id":"aea3f547bbc572ed","repo":"wavetermdev/waveterm","slug":"ensuring-connection-w","errorCode":null,"errorMessage":"ensuring connection: %w","messagePattern":"ensuring connection: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/wsh/cmd/wshcmd-conn.go","lineNumber":208,"sourceCode":"\tif err != nil {\n\t\treturn fmt.Errorf(\"connecting connection: %w\", err)\n\t}\n\tWriteStdout(\"connected connection %q\\n\", connName)\n\treturn nil\n}\n\nfunc connEnsureRun(cmd *cobra.Command, args []string) error {\n\tconnName := args[0]\n\tif err := validateConnectionName(connName); err != nil {\n\t\treturn err\n\t}\n\tdata := wshrpc.ConnExtData{\n\t\tConnName:   connName,\n\t\tLogBlockId: RpcContext.BlockId,\n\t}\n\terr := wshclient.ConnEnsureCommand(RpcClient, data, &wshrpc.RpcOpts{Timeout: 60000})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"ensuring connection: %w\", err)\n\t}\n\tWriteStdout(\"wsh ensured on connection %q\\n\", connName)\n\treturn nil\n}\n","sourceCodeStart":190,"sourceCodeEnd":213,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-conn.go#L190-L213","documentation":"Returned by connEnsureRun when the ConnEnsureCommand RPC fails (60-second timeout). \"Ensure\" means make sure wsh is installed/running on the connection; this error means that guarantee could not be established server-side.","triggerScenarios":"Running `wsh conn ensure <conn>` when the connection cannot be established or wsh cannot be verified/installed on the remote within 60s, or the RPC transport errors.","commonSituations":"Remote host unreachable, wsh binary missing or incompatible on the remote, first-time setup exceeding the timeout, stale connection state.","solutions":["Connect first with `wsh conn connect <conn>` then retry ensure","Check the wrapped inner error for timeout vs. remote install failure","Verify the remote can run wsh (architecture/OS compatibility, exec permissions)","Retry after confirming host reachability; investigate server logs for install errors"],"exampleFix":"// before\nwsh conn ensure newhost\n// error: ensuring connection: timeout\n// after\nwsh conn connect newhost   # establish first\nwsh conn ensure newhost","handlingStrategy":"retry","validationCode":"if err := validateConnectionName(connName); err != nil {\n    return err\n}\nstatus, err := wshclient.ConnStatusCommand(RpcClient, nil)\nif err == nil && !slices.ContainsFunc(status, func(c wshrpc.ConnStatusEntry) bool { return c.ConnName == connName }) {\n    return fmt.Errorf(\"connection %q unknown; connect first\", connName)\n}","typeGuard":null,"tryCatchPattern":"var err error\nfor attempt := 0; attempt < 2; attempt++ {\n    err = wshclient.ConnEnsureCommand(RpcClient, data, &wshrpc.RpcOpts{Timeout: 60000})\n    if err == nil {\n        break\n    }\n    time.Sleep(2 * time.Second)\n}\nif err != nil {\n    return fmt.Errorf(\"ensuring connection: %w\", err)\n}","preventionTips":["Connect before ensure on first-time setups","Retry ensure — first-time installs can exceed the 60s budget","Confirm remote OS/arch supports the wsh binary","Inspect server logs when ensure repeatedly fails for the same host"],"tags":["cli","rpc","wsh-install","timeout"],"backgroundTag":"rpc-call-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}