wavetermdev/waveterm · error

connecting connection: %w

Error message

connecting connection: %w

What it means

Returned by connConnectRun when the ConnConnectCommand RPC fails (60-second timeout). It means the server could not establish the requested connection to the host. The underlying error is preserved via %w.

Source

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

		} else {
			WriteStdout("disconnected %q\n", conn.Connection)
		}
	}
	return nil
}

func connConnectRun(cmd *cobra.Command, args []string) error {
	connName := args[0]
	if err := validateConnectionName(connName); err != nil {
		return err
	}
	data := wshrpc.ConnRequest{
		Host:       connName,
		LogBlockId: RpcContext.BlockId,
	}
	err := wshclient.ConnConnectCommand(RpcClient, data, &wshrpc.RpcOpts{Timeout: 60000})
	if err != nil {
		return fmt.Errorf("connecting connection: %w", err)
	}
	WriteStdout("connected connection %q\n", connName)
	return nil
}

func connEnsureRun(cmd *cobra.Command, args []string) error {
	connName := args[0]
	if err := validateConnectionName(connName); err != nil {
		return err
	}
	data := wshrpc.ConnExtData{
		ConnName:   connName,
		LogBlockId: RpcContext.BlockId,
	}
	err := wshclient.ConnEnsureCommand(RpcClient, data, &wshrpc.RpcOpts{Timeout: 60000})
	if err != nil {
		return fmt.Errorf("ensuring connection: %w", err)
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Test raw connectivity to the host (ping/ssh) to separate network from wsh issues
2. Verify SSH credentials/keys for the connection are valid and not expired
3. Retry — 60s can be exceeded on slow links; check the wrapped error for 'timeout'
4. Confirm the connection name/config is correct via `wsh conn status` or config files

Example fix

// before
wsh conn connect badhost
// error: connecting connection: dial tcp: lookup badhost: no such host
// after
ssh badhost   # verify reachability first, fix ~/.ssh/config, then
wsh conn connect badhost

if err := validateConnectionName(connName); err != nil {
    return err
}
// pre-check raw reachability before consuming the 60s RPC budget
if host != "" && isSshStyleHost(host) {
    if err := probeSshReachability(host); err != nil {
        return fmt.Errorf("host %q unreachable, fix connectivity before connecting: %w", host, err)
    }
}

err := wshclient.ConnConnectCommand(RpcClient, data, &wshrpc.RpcOpts{Timeout: 60000})
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        return fmt.Errorf("connecting connection: timed out after 60s; check host reachability")
    }
    return fmt.Errorf("connecting connection: %w", err)
}

When it happens

Trigger: Running `wsh conn connect <conn>` when the host is unreachable, SSH/WSL authentication fails, the RPC times out at 60s, or the server rejects the ConnRequest.

Common situations: Wrong hostname in the connection config, expired SSH keys/passwords, remote host offline, firewall blocking the port, DNS failures.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• watching pid: %v
• cannot parse connection name: %w
• getting ssh connection status: %w
• playing system bell: %v
• getting wsl connection status: %w

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