{"record":{"id":"7241855bd676b3a7","repo":"wavetermdev/waveterm","slug":"disconnected-724185","errorCode":null,"errorMessage":"disconnected","messagePattern":"disconnected","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":481,"sourceCode":"\treturn conn.Connect(ctx)\n}\n\nfunc (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","sourceCodeStart":463,"sourceCodeEnd":499,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L463-L499","documentation":"WaitForConnect returns this error when DeriveConnStatus reports Status_Init or Status_Disconnected instead of Connected or Connecting — i.e. the connection is not being attempted at all or was torn down. The connect will never succeed in this state, so waiting is aborted immediately.","triggerScenarios":"Calling WaitForConnect before Connect() was ever started (Status_Init), or after the connection dropped/was closed (Status_Disconnected); the WSL distro failed to launch so the state reverted to disconnected.","commonSituations":"Calling WaitForConnect on a connection whose Connect failed earlier; wsl.exe unavailable or WSL not installed; the distro was unregistered or shut down between connect attempts; a race where Connect finished/failed before WaitForConnect began.","solutions":["Start the connection first: call conn.Connect(ctx) (or Reconnect) before WaitForConnect","Check the connection status (DeriveConnStatus) and any stored WshError/NoWshReason for the disconnect reason","Verify WSL is installed and the distro exists: 'wsl -l -v'","If the distro shut down, reconnect — WSL terminates idle distros automatically"],"exampleFix":"// before: wait without connecting\nerr := conn.WaitForConnect(ctx)\n// after\nif s := conn.DeriveConnStatus().Status; s == Status_Init || s == Status_Disconnected {\n    if err := conn.Connect(ctx); err != nil {\n        return err\n    }\n}\nerr := conn.WaitForConnect(ctx)","handlingStrategy":"validation","validationCode":"st := conn.DeriveConnStatus().Status\nif st == Status_Init || st == Status_Disconnected {\n    if err := conn.Connect(ctx); err != nil {\n        return err\n    }\n}\nerr := conn.WaitForConnect(ctx)","typeGuard":"func waitingMakesSense(conn *wslconn.WslConn) bool {\n    st := conn.DeriveConnStatus().Status\n    return st == wslconn.Status_Connecting || st == wslconn.Status_Init\n}","tryCatchPattern":"if err := conn.WaitForConnect(ctx); err != nil {\n    if err.Error() == \"disconnected\" {\n        // (re)start the connection, then wait again\n        if cerr := conn.Connect(ctx); cerr != nil {\n            return cerr\n        }\n        err = conn.WaitForConnect(ctx)\n    }\n}","preventionTips":["Always call Connect before WaitForConnect","Check DeriveConnStatus before waiting; never wait on a torn-down connection","Verify WSL and the distro are installed/registered ('wsl -l -v')","Expect idle WSL distros to shut down; reconnect on demand"],"tags":["wsl","connection","disconnected","lifecycle"],"backgroundTag":"connection-disconnected","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}