{"record":{"id":"3b5c2fe089e69978","repo":"wavetermdev/waveterm","slug":"unknown-status-q-3b5c2f","errorCode":null,"errorMessage":"unknown status: %q","messagePattern":"unknown status: %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":486,"sourceCode":"\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())\n\tif !connectAllowed {\n\t\tconn.Infof(ctx, \"cannot connect to %q when status is %q\\n\", conn.GetName(), conn.GetStatus())","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L468-L504","documentation":"WaitForConnect is an exhaustive status switch: Connected returns nil, Connecting keeps polling, Init/Disconnected and Error have dedicated errors, and any other status value falls through to 'unknown status: %q'. Hitting it means DeriveConnStatus returned a status string the waiter doesn't recognize — normally impossible with the built-in status constants, but possible with an unexpected/extended status value.","triggerScenarios":"Calling WaitForConnect when DeriveConnStatus yields a status outside the known set (Status_Connected/Connecting/Init/Disconnected/Error) — e.g. after code changes introducing a new status constant without updating WaitForConnect, or a custom/derived status implementation.","commonSituations":"Running a mismatched build where a new ConnStatus value was added elsewhere but WaitForConnect wasn't updated; mocking DeriveConnStatus in tests with an arbitrary status string.","solutions":["Log the quoted status value from the error and check it against the status constants defined in this package","Update WaitForConnect (or the status derivation) to handle any newly added status constant","If seen in tests/mocks, fix the mock to return a real status constant","Retry the connection; an unknown transient status typically resolves to a known state on the next poll"],"exampleFix":"// before: new status not handled\nif status.Status == Status_Error {\n    return fmt.Errorf(\"error: %v\", status.Error)\n}\n// after\nif status.Status == Status_Error {\n    return fmt.Errorf(\"error: %v\", status.Error)\n}\nif status.Status == Status_NewConnecting { // handle the new constant\n    continue\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isKnownStatus(s ConnStatus) bool {\n    switch s {\n    case Status_Connected, Status_Connecting, Status_Init, Status_Disconnected, Status_Error:\n        return true\n    }\n    return false\n}","tryCatchPattern":"if err := conn.WaitForConnect(ctx); err != nil {\n    if strings.HasPrefix(err.Error(), \"unknown status:\") {\n        log.Printf(\"unrecognized conn status %s — upgrade the client or fix DeriveConnStatus\", err)\n    }\n}","preventionTips":["When adding a new ConnStatus constant, update WaitForConnect's switch in the same change","Use only the package's status constants — never arbitrary strings in DeriveConnStatus implementations","Fix test mocks to return real status values","Add a lint/test asserting every status constant is handled in WaitForConnect"],"tags":["wsl","connection","status","invariant"],"backgroundTag":"unknown-connection-status","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}