wavetermdev/waveterm · critical

unable to request connection domain socket: %v

Error message

unable to request connection domain socket: %v

What it means

After generating a socket name, the code asks the SSH client (via the remote server) to create a Unix domain socket listener at /tmp/waveterm-<rand>.sock using ListenUnix. If the remote side cannot open it — bad path, permissions, path collision, or transport failure — the error is wrapped as 'unable to request connection domain socket'.

Source

Thrown at pkg/remote/conncontroller/conncontroller.go:287

func (conn *SSHConn) OpenDomainSocketListener(ctx context.Context) error {
	conn.Infof(ctx, "running OpenDomainSocketListener...\n")
	allowed := WithLockRtn(conn, func() bool {
		return conn.Status == Status_Connecting
	})
	if !allowed {
		return fmt.Errorf("cannot open domain socket for %q when status is %q", conn.GetName(), conn.GetStatus())
	}
	client := conn.GetClient()
	randStr, err := utilfn.RandomHexString(16) // 64-bits of randomness
	if err != nil {
		return fmt.Errorf("error generating random string: %w", err)
	}
	sockName := fmt.Sprintf("/tmp/waveterm-%s.sock", randStr)
	conn.Infof(ctx, "generated domain socket name %s\n", sockName)
	listener, err := client.ListenUnix(sockName)
	if err != nil {
		return fmt.Errorf("unable to request connection domain socket: %v", err)
	}
	conn.WithLock(func() {
		conn.DomainSockName = sockName
		conn.DomainSockListener = listener
	})
	conn.Infof(ctx, "successfully connected domain socket\n")
	go func() {
		defer func() {
			panichandler.PanicHandler("conncontroller:OpenDomainSocketListener", recover())
		}()
		defer conn.WithLock(func() {
			conn.DomainSockListener = nil
			conn.DomainSockName = ""
		})
		monitor := conn.GetMonitor()
		var updateCallback func()
		if monitor != nil {
			updateCallback = monitor.UpdateLastActivityTime

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the remote sshd permits Unix domain socket forwarding (streamlocal) and /tmp is writable
2. Remove stale /tmp/waveterm-*.sock files on the remote host
3. Check SSH connectivity/reconnect; a dropped connection will make ListenUnix fail
4. Confirm wsh is installed and up to date on the remote so the server side supports the socket request

Example fix

// before
listener, err := client.ListenUnix(sockName)
// after (caller-side mitigation)
listener, err := client.ListenUnix(sockName)
if err != nil {
    // clean stale sockets and retry once
    _ = client.CleanupStaleSockets(ctx)
    listener, err = client.ListenUnix(sockName)
}

// verify remote prerequisites before enabling wsh
if conn.GetStatus() != remote.Status_Connected && conn.GetStatus() != remote.Status_Connecting {
    return fmt.Errorf("ssh connection not ready")
}

err := conn.OpenDomainSocketListener(ctx)
if err != nil && strings.Contains(err.Error(), "unable to request connection domain socket") {
    log.Printf("wsh domain socket failed: %v", err)
    // cleanup stale /tmp/waveterm-*.sock on remote and retry once
}

When it happens

Trigger: client.ListenUnix(sockName) fails: the remote SSH server rejects the streamlocal forward, /tmp is not writable, the socket path already exists, or the SSH connection dropped.

Common situations: Remote host restricts Unix socket forwarding; stale /tmp/waveterm-*.sock files; sshd without streamlocal support; flaky SSH connection dying mid-setup; restricted containers/chroot jails.

Related errors

• failed to list workspaces: %v
• failed to list blocks from all %d workspace(s)
• getting ssh connection status: %w
• error creating listener at %v: %v
• cannot create unix listener: %v

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