{"record":{"id":"66cb14ee38c53cc3","repo":"wavetermdev/waveterm","slug":"unknown-connection-status-q-66cb14","errorCode":null,"errorMessage":"unknown connection status %q","messagePattern":"unknown connection status %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":776,"sourceCode":"\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":758,"sourceCodeEnd":788,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L758-L788","documentation":"EnsureConnection()'s status switch has cases for init/disconnected/connecting/connected/error; this default-branch error means DeriveConnStatus returned a status string outside the known set — practically a state-machine invariant violation or a future/renamed status value.","triggerScenarios":"DeriveConnStatus returns a status string not among init|connecting|connected|disconnected|error — only possible if a new status constant was added without updating EnsureConnection, or status was corrupted to an arbitrary string.","commonSituations":"Running a mixed-version setup where a newer backend reports a new status to an older command handler; custom code writing an invalid value into conn.Status; a bug in status derivation.","solutions":["Log the full unexpected status value from the error and check it against pkg/wslconn status constants","Update Wave/wsh to matching versions to avoid mixed-version status values","Reset the connection state via Disconnect and reconnect","If you modified status constants, add the missing case to EnsureConnection's switch","Report as a bug if seen on an unmodified install — this branch should be unreachable"],"exampleFix":"// developer fix\n// before\ncase Status_Error:\n    return fmt.Errorf(\"connection error: %s\", connStatus.Error)\ndefault:\n    return fmt.Errorf(\"unknown connection status %q\", connStatus.Status)\n// after: add the new status to the switch\n// case Status_New: return conn.Connect(ctx)","handlingStrategy":"type-guard","validationCode":"var validStatuses = map[string]bool{\n    wslconn.Status_Init: true, wslconn.Status_Connecting: true,\n    wslconn.Status_Connected: true, wslconn.Status_Disconnected: true,\n    wslconn.Status_Error: true,\n}\nif !validStatuses[st.Status] {\n    return fmt.Errorf(\"corrupt status %q; reset connection\", st.Status)\n}","typeGuard":"func isKnownStatus(s string) bool {\n    switch s {\n    case wslconn.Status_Init, wslconn.Status_Connecting,\n        wslconn.Status_Connected, wslconn.Status_Disconnected,\n        wslconn.Status_Error:\n        return true\n    }\n    return false\n}","tryCatchPattern":"if err := wslconn.EnsureConnection(ctx, name); err != nil {\n    if strings.HasPrefix(err.Error(), \"unknown connection status\") {\n        // reset to a known state\n        wslconn.DisconnectClient(name)\n        return wslconn.EnsureConnection(ctx, name)\n    }\n    return err\n}","preventionTips":["Never write arbitrary strings into conn.Status","Keep status constants and switches in sync when adding states","Pin client/backend versions together","Report occurrences as bugs — this branch is intended to be unreachable"],"tags":["go","state-machine","switch-default","wsl"],"backgroundTag":"unknown-connection-status","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}