{"record":{"id":"a8e378e2067eca5d","repo":"wavetermdev/waveterm","slug":"ssh-connection-not-found-s","errorCode":null,"errorMessage":"ssh connection not found: %s","messagePattern":"ssh connection not found: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/shellcontroller.go","lineNumber":360,"sourceCode":"\t\t}\n\t\tconnStatus := wslConn.DeriveConnStatus()\n\t\tif connStatus.Status != conncontroller.Status_Connected {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"wsl connection %s not connected, cannot start shellproc\", remoteName)\n\t\t}\n\t\trtn.ConnType = ConnType_Wsl\n\t\trtn.WslConn = wslConn\n\t\trtn.WshEnabled = wshEnabled && wslConn.WshEnabled.Load()\n\t} else if conncontroller.IsLocalConnName(remoteName) {\n\t\trtn.ConnType = ConnType_Local\n\t\trtn.WshEnabled = wshEnabled\n\t} else {\n\t\topts, err := remote.ParseOpts(remoteName)\n\t\tif err != nil {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"invalid ssh remote name (%s): %w\", remoteName, err)\n\t\t}\n\t\tconn := conncontroller.MaybeGetConn(opts)\n\t\tif conn == nil {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"ssh connection not found: %s\", remoteName)\n\t\t}\n\t\tconnStatus := conn.DeriveConnStatus()\n\t\tif connStatus.Status != conncontroller.Status_Connected {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"ssh connection %s not connected, cannot start shellproc\", remoteName)\n\t\t}\n\t\trtn.ConnType = ConnType_Ssh\n\t\trtn.SshConn = conn\n\t\trtn.WshEnabled = wshEnabled && conn.WshEnabled.Load()\n\t}\n\terr := rtn.getRemoteInfoAndShellType(blockMeta)\n\tif err != nil {\n\t\treturn ConnUnion{}, err\n\t}\n\treturn rtn, nil\n}\n\nfunc (bc *ShellController) setupAndStartShellProcess(logCtx context.Context, rc *RunShellOpts, blockMeta waveobj.MetaMapType) (*shellexec.ShellProc, error) {\n\t// create a circular blockfile for the output","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/shellcontroller.go#L342-L378","documentation":"Thrown when the remote name parses as a valid SSH target but conncontroller.MaybeGetConn(opts) returns nil — meaning no active connection object is registered for those SSH options. Wave cannot start a shellproc on an SSH host for which it has no live connection instance.","triggerScenarios":"DoRunShellCommand on a block with an SSH remoteName where no connection for those parsed opts exists in the connection controller (remote never connected this session, or connection was cleaned up/closed).","commonSituations":"Restoring a session/workspace referencing a remote that was never connected after app restart; remote connection dropped and was garbage-collected; connecting to a host first time from a restored tab; typo'd host matches nothing in active connections.","solutions":["Connect to the SSH remote first (ensure it appears in the connected remotes list), then retry the shell command","Verify the host/user/port match an existing configured remote — a mismatch creates opts for a nonexistent connection","Re-create the terminal block against a currently-connected remote","Check ssh config/keys so the initial connection to the remote can succeed"],"exampleFix":"// before: starting shell on a not-yet-connected ssh remote\nrunShellCommand(blockId, sshRemoteName)\n\n// after: ensure connection exists and is up first\nif conncontroller.MaybeGetConn(opts) == nil {\n    if err := conncontroller.ConnectToConn(opts); err != nil {\n        return err\n    }\n}\nrunShellCommand(blockId, sshRemoteName)","handlingStrategy":"validation","validationCode":"opts, err := remote.ParseOpts(remoteName)\nif err == nil && conncontroller.MaybeGetConn(opts) == nil {\n    if err := conncontroller.ConnectToConn(opts); err != nil {\n        return fmt.Errorf(\"connect to %s first: %w\", remoteName, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)\nif err != nil && strings.HasPrefix(err.Error(), \"ssh connection not found\") {\n    // trigger reconnect flow for the remote, then retry once","preventionTips":["Ensure remotes are connected at session restore before opening terminal blocks","Keep block metadata's connection name in sync with the saved remote entry","Avoid hand-editing connection identifiers in state files"],"tags":["ssh","connection-state","session-restore"],"backgroundTag":"ssh-connection-not-found","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}