{"record":{"id":"9640e3857e0ee96e","repo":"wavetermdev/waveterm","slug":"error-v-9640e3","errorCode":null,"errorMessage":"error: %v","messagePattern":"error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":484,"sourceCode":"func (conn *WslConn) WaitForConnect(ctx context.Context) error {\n\tfor {\n\t\tstatus := conn.DeriveConnStatus()\n\t\tif status.Status == Status_Connected {\n\t\t\treturn nil\n\t\t}\n\t\tif status.Status == Status_Connecting {\n\t\t\tselect {\n\t\t\tcase <-ctx.Done():\n\t\t\t\treturn fmt.Errorf(\"context timeout\")\n\t\t\tcase <-time.After(100 * time.Millisecond):\n\t\t\t\tcontinue\n\t\t\t}\n\t\t}\n\t\tif status.Status == Status_Init || status.Status == Status_Disconnected {\n\t\t\treturn fmt.Errorf(\"disconnected\")\n\t\t}\n\t\tif status.Status == Status_Error {\n\t\t\treturn fmt.Errorf(\"error: %v\", status.Error)\n\t\t}\n\t\treturn fmt.Errorf(\"unknown status: %q\", status.Status)\n\t}\n}\n\n// does not return an error since that error is stored inside of WslConn\nfunc (conn *WslConn) Connect(ctx context.Context) error {\n\tvar connectAllowed bool\n\tconn.WithLock(func() {\n\t\tif conn.Status == Status_Connecting || conn.Status == Status_Connected {\n\t\t\tconnectAllowed = false\n\t\t} else {\n\t\t\tconn.Status = Status_Connecting\n\t\t\tconn.Error = \"\"\n\t\t\tconnectAllowed = true\n\t\t}\n\t})\n\tlog.Printf(\"Connect %s\\n\", conn.GetName())","sourceCodeStart":466,"sourceCodeEnd":502,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L466-L502","documentation":"WaitForConnect returns this error when DeriveConnStatus reports Status_Error; the underlying connection failure message (status.Error) is embedded via 'error: %v'. It is the surface for whatever caused the WSL connection itself to fail (launch failure, exec error, etc.).","triggerScenarios":"Calling WaitForConnect while the WslConn is in Status_Error — e.g. wsl.exe failed to spawn, the distro command errored, or Connect internally captured an error and set Status_Error.","commonSituations":"WSL not installed or 'wsl' not on PATH; the requested distro name doesn't exist; WSL service crashed; corrupt distro; Windows-side permission problems launching wsl.exe.","solutions":["Read the embedded status.Error message — it names the underlying failure; fix that first","Verify WSL works independently: run 'wsl -l -v' and 'wsl -d <distro> echo ok' from a shell","Confirm the distro name configured in Wave matches an installed WSL distro","If WSL is broken, repair it (wsl --update / reinstall distro) then reconnect"],"exampleFix":"// before: opaque handling\nerr := conn.WaitForConnect(ctx)\n// after\nif err != nil && strings.HasPrefix(err.Error(), \"error: \") {\n    log.Printf(\"connection failed with underlying error: %s\", strings.TrimPrefix(err.Error(), \"error: \"))\n}","handlingStrategy":"type-guard","validationCode":"// confirm WSL itself works before attempting a connection\nif err := exec.Command(\"wsl\", \"-l\", \"-v\").Run(); err != nil {\n    return fmt.Errorf(\"WSL is not installed or broken: %w\", err)\n}","typeGuard":"func isConnStatusError(err error) bool {\n    return err != nil && strings.HasPrefix(err.Error(), \"error: \")\n}","tryCatchPattern":"if err := conn.WaitForConnect(ctx); err != nil {\n    if isConnStatusError(err) {\n        underlying := strings.TrimPrefix(err.Error(), \"error: \")\n        log.Printf(\"WSL connection failed: %s\", underlying) // fix per underlying message\n    }\n}","preventionTips":["Validate WSL installation and distro name before connecting","Surface the embedded status.Error text to users instead of the generic wrapper","Run 'wsl --update' when wsl.exe errors persist","Match the configured distro name exactly to an installed distro"],"tags":["wsl","connection","connection-error"],"backgroundTag":"wsl-connection-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}