wavetermdev/waveterm · error

ensuring connection: %w

Error message

ensuring connection: %w

What it means

Returned by connEnsureRun when the ConnEnsureCommand RPC fails (60-second timeout). "Ensure" means make sure wsh is installed/running on the connection; this error means that guarantee could not be established server-side.

Source

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

	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)
	}
	WriteStdout("wsh ensured on connection %q\n", connName)
	return nil
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Connect first with `wsh conn connect <conn>` then retry ensure
2. Check the wrapped inner error for timeout vs. remote install failure
3. Verify the remote can run wsh (architecture/OS compatibility, exec permissions)
4. Retry after confirming host reachability; investigate server logs for install errors

Example fix

// before
wsh conn ensure newhost
// error: ensuring connection: timeout
// after
wsh conn connect newhost   # establish first
wsh conn ensure newhost

if err := validateConnectionName(connName); err != nil {
    return err
}
status, err := wshclient.ConnStatusCommand(RpcClient, nil)
if err == nil && !slices.ContainsFunc(status, func(c wshrpc.ConnStatusEntry) bool { return c.ConnName == connName }) {
    return fmt.Errorf("connection %q unknown; connect first", connName)
}

var err error
for attempt := 0; attempt < 2; attempt++ {
    err = wshclient.ConnEnsureCommand(RpcClient, data, &wshrpc.RpcOpts{Timeout: 60000})
    if err == nil {
        break
    }
    time.Sleep(2 * time.Second)
}
if err != nil {
    return fmt.Errorf("ensuring connection: %w", err)
}

When it happens

Trigger: Running `wsh conn ensure <conn>` when the connection cannot be established or wsh cannot be verified/installed on the remote within 60s, or the RPC transport errors.

Common situations: Remote host unreachable, wsh binary missing or incompatible on the remote, first-time setup exceeding the timeout, stale connection state.

Related errors

• reinstalling connection: %w
• disconnecting %q error: %w
• reading terminal output: %w
• deleting secret: %w
• opening secrets UI: %w

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