What causes "cannot parse connection name: %w" in wavetermdev/waveterm?

Fix the connection name syntax: use user@host[:port] (or wsl://... which bypasses parsing)

cannot parse connection name: %w

Error message

cannot parse connection name: %w

What it means

Error from validateConnectionName, used by `wsh conn connect|disconnect|ensure|reinstall`. For any name that is not a wsl:// URI, the code calls remote.ParseOpts to validate the connection name as a valid remote connection spec (e.g. user@host:port). If parsing fails, the name is not a recognized connection string and the underlying parse error is wrapped.

Source

Thrown at cmd/wsh/cmd/wshcmd-conn.go:83

	RunE:    connEnsureRun,
	PreRunE: preRunSetupRpcClient,
}

func init() {
	rootCmd.AddCommand(connCmd)
	connCmd.AddCommand(connStatusCmd)
	connCmd.AddCommand(connReinstallCmd)
	connCmd.AddCommand(connDisconnectCmd)
	connCmd.AddCommand(connDisconnectAllCmd)
	connCmd.AddCommand(connConnectCmd)
	connCmd.AddCommand(connEnsureCmd)
}

func validateConnectionName(name string) error {
	if !strings.HasPrefix(name, "wsl://") {
		_, err := remote.ParseOpts(name)
		if err != nil {
			return fmt.Errorf("cannot parse connection name: %w", err)
		}
	}
	return nil
}

func getAllConnStatus() ([]wshrpc.ConnStatus, error) {
	var allResp []wshrpc.ConnStatus
	sshResp, err := wshclient.ConnStatusCommand(RpcClient, nil)
	if err != nil {
		return nil, fmt.Errorf("getting ssh connection status: %w", err)
	}
	allResp = append(allResp, sshResp...)
	wslResp, err := wshclient.WslStatusCommand(RpcClient, nil)
	if err != nil {
		return nil, fmt.Errorf("getting wsl connection status: %w", err)
	}
	allResp = append(allResp, wslResp...)
	return allResp, nil

View on GitHub (pinned to a4447c1563)

Solutions

Fix the connection name syntax: use user@host[:port] (or wsl://... which bypasses parsing)
Check saved connection names (`wsh conn status` or ~/.ssh config) for the exact spelling
Trim whitespace and remove quotes from the argument
Ensure the remote name matches one registered in your connection config

Example fix

// before
err := validateConnectionName("myhost:")
// after
err := validateConnectionName("user@myhost:22")

Defensive patterns

Strategy: validation

Validate before calling

func validateConnName(name string) error {
    if strings.HasPrefix(name, "wsl://") { return nil }
    if name == "" || strings.ContainsAny(name, " \t\"") { return fmt.Errorf("connection name has whitespace/quotes: %q", name) }
    if !strings.Contains(name, "@") && !strings.Contains(name, ":") { return fmt.Errorf("expected user@host[:port], got %q", name) }
    return nil
}

Try / catch

if err := validateConnectionName(connName); err != nil {
    var parseErr *remote.ParseOptsError
    if errors.As(err, &parseErr) { /* fix syntax user@host[:port] */ }
}

Prevention

Use the exact saved connection name from `wsh conn status`
Follow user@host[:port] syntax; use wsl:// prefix for WSL
Strip quotes/whitespace when interpolating names in shell scripts

When it happens

Trigger: Passing a malformed connection name to any of the conn subcommands: missing user/host, bad port syntax, unparseable SSH-style spec, or a typo in a saved connection name that no longer resolves.

Common situations: Typos like 'myhost:' or 'user@'; using a display/alias name where a connection spec is required; copying a name with stray whitespace or quotes; config entries for saved connections that were deleted.

Related errors

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