wavetermdev/waveterm · error

ssh connection not found: %s

Error message

ssh connection not found: %s

What it means

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.

Source

Thrown at pkg/blockcontroller/shellcontroller.go:360

		}
		connStatus := wslConn.DeriveConnStatus()
		if connStatus.Status != conncontroller.Status_Connected {
			return ConnUnion{}, fmt.Errorf("wsl connection %s not connected, cannot start shellproc", remoteName)
		}
		rtn.ConnType = ConnType_Wsl
		rtn.WslConn = wslConn
		rtn.WshEnabled = wshEnabled && wslConn.WshEnabled.Load()
	} else if conncontroller.IsLocalConnName(remoteName) {
		rtn.ConnType = ConnType_Local
		rtn.WshEnabled = wshEnabled
	} else {
		opts, err := remote.ParseOpts(remoteName)
		if err != nil {
			return ConnUnion{}, fmt.Errorf("invalid ssh remote name (%s): %w", remoteName, err)
		}
		conn := conncontroller.MaybeGetConn(opts)
		if conn == nil {
			return ConnUnion{}, fmt.Errorf("ssh connection not found: %s", remoteName)
		}
		connStatus := conn.DeriveConnStatus()
		if connStatus.Status != conncontroller.Status_Connected {
			return ConnUnion{}, fmt.Errorf("ssh connection %s not connected, cannot start shellproc", remoteName)
		}
		rtn.ConnType = ConnType_Ssh
		rtn.SshConn = conn
		rtn.WshEnabled = wshEnabled && conn.WshEnabled.Load()
	}
	err := rtn.getRemoteInfoAndShellType(blockMeta)
	if err != nil {
		return ConnUnion{}, err
	}
	return rtn, nil
}

func (bc *ShellController) setupAndStartShellProcess(logCtx context.Context, rc *RunShellOpts, blockMeta waveobj.MetaMapType) (*shellexec.ShellProc, error) {
	// create a circular blockfile for the output

View on GitHub (pinned to a4447c1563)

Solutions

1. Connect to the SSH remote first (ensure it appears in the connected remotes list), then retry the shell command
2. Verify the host/user/port match an existing configured remote — a mismatch creates opts for a nonexistent connection
3. Re-create the terminal block against a currently-connected remote
4. Check ssh config/keys so the initial connection to the remote can succeed

Example fix

// before: starting shell on a not-yet-connected ssh remote
runShellCommand(blockId, sshRemoteName)

// after: ensure connection exists and is up first
if conncontroller.MaybeGetConn(opts) == nil {
    if err := conncontroller.ConnectToConn(opts); err != nil {
        return err
    }
}
runShellCommand(blockId, sshRemoteName)

opts, err := remote.ParseOpts(remoteName)
if err == nil && conncontroller.MaybeGetConn(opts) == nil {
    if err := conncontroller.ConnectToConn(opts); err != nil {
        return fmt.Errorf("connect to %s first: %w", remoteName, err)
    }
}

proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)
if err != nil && strings.HasPrefix(err.Error(), "ssh connection not found") {
    // trigger reconnect flow for the remote, then retry once

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• ssh connection %s not connected, cannot start shellproc
• cannot open domain socket for %q when status is %q
• ssh client is not connected
• window ${windowId} not found
• encryption is not available

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/a8e378e2067eca5d. Report an issue: GitHub.