What causes "invalid ssh remote name (%s): %w" in wavetermdev/waveterm?

Fix the connection name stored in the block's connection: meta so it is a valid user@host[:port] SSH specifier

invalid ssh remote name (%s): %w

Error message

invalid ssh remote name (%s): %w

What it means

Wraps an error from remote.ParseOpts when the remoteName is neither a WSL name nor a local connection name and cannot be parsed as a valid SSH target string. ParseOpts validates user@host:port syntax, so any malformed specifier produces this wrapped error.

Source

Thrown at pkg/blockcontroller/shellcontroller.go:356

		wslName := strings.TrimPrefix(remoteName, "wsl://")
		wslConn := wslconn.GetWslConn(wslName)
		if wslConn == nil {
			return ConnUnion{}, fmt.Errorf("wsl connection not found: %s", remoteName)
		}
		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

View on GitHub (pinned to a4447c1563)

Solutions

Fix the connection name stored in the block's connection: meta so it is a valid user@host[:port] SSH specifier
Verify the remote still exists in the saved remotes list (it may have been deleted or renamed); re-select a valid remote
Check for typos/whitespace/invalid port in the connection string before passing it
If the block is meant to be local, set the connection to the local connection name instead

Example fix

// before: passing a malformed remote name from block meta
remoteName := blockMeta[waveobj.MetaKey_Connection]

// after: validate parseability first
if _, err := remote.ParseOpts(remoteName); err != nil {
    return fmt.Errorf("fix connection name %q: %w", remoteName, err)
}

Defensive patterns

Strategy: validation

Validate before calling

if !conncontroller.IsLocalConnName(remoteName) {
    if _, err := remote.ParseOpts(remoteName); err != nil {
        return fmt.Errorf("reject bad remote %q before shell start: %w", remoteName, err)
    }
}

Try / catch

proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)
var pe *remote.ParseOptsError
if errors.As(err, &pe) {
    // prompt user to fix the connection string in block settings
}

Prevention

Always pick remotes from the saved remote list, never type free-form strings
Validate connection strings (user@host[:port]) on input/save
Clean up blocks referencing deleted remotes during workspace restore

When it happens

Trigger: DoRunShellCommand on a block whose remoteName is not IsLocalConnName and fails remote.ParseOpts — e.g. empty string, stray whitespace, invalid port, or malformed user@host syntax.

Common situations: Block metadata retains a stale/corrupted connection name after a remote was deleted or renamed; user hand-edited the connection string in settings; a connection name with unsupported characters was imported from another machine's config.

Related errors

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