{"record":{"id":"5bae8ce7e2d11cab","repo":"wavetermdev/waveterm","slug":"connection-not-found-s-5bae8c","errorCode":null,"errorMessage":"connection not found: %s","messagePattern":"connection not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":763,"sourceCode":"\t\trtn = &WslConn{Lock: &sync.Mutex{}, Status: Status_Init, Name: connName, WshEnabled: &atomic.Bool{}, HasWaiter: &atomic.Bool{}, cancelFn: nil}\n\t\tclientControllerMap[name] = rtn\n\t}\n\treturn rtn\n}\n\nfunc GetWslConn(name string) *WslConn {\n\tconn := getConnInternal(name)\n\treturn conn\n}\n\n// 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)","sourceCodeStart":745,"sourceCodeEnd":781,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L745-L781","documentation":"EnsureConnection() looks up the connection by name via GetWslConn and throws this when no connection with that name is registered. It is the pre-flight check for RPC commands that require an established connection (e.g. ConnEnsureCommand).","triggerScenarios":"Calling EnsureConnection/ConnEnsureCommand with a connName that has no registered WSLConn — typo in the connection name, the profile was deleted, or the connection was never initialized because its config isn't loaded.","commonSituations":"Renamed or deleted a connection profile in Wave but a block/command still references the old name; passing a host identifier instead of the connection name; config file edited by hand with a stale connection name.","solutions":["List available connections (connection: list / GetConnections) and use an exact registered name","Verify the connection profile still exists in the Wave config and re-add it if deleted","Check for typos/whitespace in connName and that you pass the connection name, not a host or alias","Reload config/restart Wave if the profile was just added and isn't yet registered"],"exampleFix":"// before\nerr := wslconn.EnsureConnection(ctx, \"MyLaptop\") // 'connection not found: MyLaptop'\n// after\nconns := wconfig.GetConnectionConfigs()\nif _, ok := conns[\"MyLaptop\"]; !ok {\n    return fmt.Errorf(\"profile missing; create it first\")\n}\nerr := wslconn.EnsureConnection(ctx, \"MyLaptop\")","handlingStrategy":"validation","validationCode":"func connectionExists(name string) bool {\n    for _, c := range wslconn.GetConnections() {\n        if c.GetName() == name {\n            return true\n        }\n    }\n    return false\n}\nif !connectionExists(connName) {\n    return fmt.Errorf(\"profile %q does not exist\", connName)\n}","typeGuard":"func isKnownConn(c *wslconn.WslConn) bool { return c != nil }","tryCatchPattern":"if err := wslconn.EnsureConnection(ctx, name); err != nil {\n    if strings.HasPrefix(err.Error(), \"connection not found\") {\n        return fmt.Errorf(\"profile %q missing; pick from connection: list\", name)\n    }\n    return err\n}","preventionTips":["Validate connection names against the config before use","Update references after renaming/deleting profiles","Use connection pickers rather than free-text input","Reload config after manual edits"],"tags":["go","connection-lookup","configuration","wsl"],"backgroundTag":"connection-not-found","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}