{"record":{"id":"15a84f2a6bfacfca","repo":"wavetermdev/waveterm","slug":"connection-error-s-15a84f","errorCode":null,"errorMessage":"connection error: %s","messagePattern":"connection error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":774,"sourceCode":"// Convenience function for ensuring a connection is established\nfunc EnsureConnection(ctx context.Context, connName string) error {\n\tif connName == \"\" {\n\t\treturn nil\n\t}\n\tconn := GetWslConn(connName)\n\tif conn == nil {\n\t\treturn fmt.Errorf(\"connection not found: %s\", connName)\n\t}\n\tconnStatus := conn.DeriveConnStatus()\n\tswitch connStatus.Status {\n\tcase Status_Connected:\n\t\treturn nil\n\tcase Status_Connecting:\n\t\treturn conn.WaitForConnect(ctx)\n\tcase Status_Init, Status_Disconnected:\n\t\treturn conn.Connect(ctx)\n\tcase Status_Error:\n\t\treturn fmt.Errorf(\"connection error: %s\", connStatus.Error)\n\tdefault:\n\t\treturn fmt.Errorf(\"unknown connection status %q\", connStatus.Status)\n\t}\n}\n\nfunc DisconnectClient(connName string) error {\n\tconn := getConnInternal(connName)\n\tif conn == nil {\n\t\treturn fmt.Errorf(\"client %q not found\", connName)\n\t}\n\terr := conn.Close()\n\treturn err\n}\n","sourceCodeStart":756,"sourceCodeEnd":788,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L756-L788","documentation":"EnsureConnection() throws this when the connection's derived status is Status_Error, surfacing the stored connStatus.Error string. The connection previously failed (a prior connectInternal error set Status_Error), and instead of retrying, EnsureConnection reports the stored failure to the caller.","triggerScenarios":"Calling EnsureConnection/ConnEnsureCommand for a connection whose last Connect() attempt failed and left Status='error' — e.g. distro unreachable, domain socket failure, or the double-connect error 1600 previously stored.","commonSituations":"WSL distro not running or uninstalled since last use; wsl.exe missing from PATH; previous connection attempt crashed leaving persistent error state; stale connection after Windows sleep/resume.","solutions":["Read the included connStatus.Error detail to find the root cause","Call Disconnect/Reconnect to reset state and retry the connect from Status_Disconnected","Verify the distro exists ('wsl -l -v') and starts cleanly; run 'wsl --shutdown' to clear stuck state","Check that wsl.exe is on PATH and WSL is properly installed","If the error persists, inspect connection logs (conn.Infof output) for the underlying failure"],"exampleFix":"// before\nerr := wslconn.EnsureConnection(ctx, name) // 'connection error: <stale error>'\n// after\nstatus := wslconn.DeriveConnStatusFor(name)\nif status.Status == wslconn.Status_Error {\n    wslconn.DisconnectClient(name) // reset state\n}\nerr := wslconn.EnsureConnection(ctx, name)","handlingStrategy":"retry","validationCode":"st := wslconn.DeriveConnStatusFor(name)\nif st != nil && st.Status == wslconn.Status_Error {\n    // reset before ensure, otherwise EnsureConnection just re-reports the old error\n    wslconn.DisconnectClient(name)\n}","typeGuard":null,"tryCatchPattern":"if err := wslconn.EnsureConnection(ctx, name); err != nil {\n    if strings.HasPrefix(err.Error(), \"connection error\") {\n        // reset and retry once\n        wslconn.DisconnectClient(name)\n        return wslconn.EnsureConnection(ctx, name)\n    }\n    return err\n}","preventionTips":["Reset errored connections before re-ensuring","Run 'wsl --shutdown' after Windows sleep/resume oddities","Verify distro health (wsl -l -v) before connecting","Surface the embedded connStatus.Error to users for the root cause"],"tags":["go","connection-state","wsl","error-propagation"],"backgroundTag":"connection-error-state","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}