wavetermdev/waveterm · error

error opening domain socket listener: %w

Error message

error opening domain socket listener: %w

What it means

tryEnableWsh wraps any failure from OpenDomainSocketListener() with this error. It means the Unix-domain socket listener for the wsh connserver inside the WSL distro could not be created, so wsh extension setup is aborted and the connection reports a NoWshReason of 'error opening domain socket'.

Source

Thrown at pkg/wslconn/wslconn.go:607

	enableWsh, askBeforeInstall := conn.getConnWshSettings()
	conn.Infof(ctx, "wsh settings enable:%v ask:%v\n", enableWsh, askBeforeInstall)
	if !enableWsh {
		return WshCheckResult{NoWshReason: "conn:wshenabled set to false"}
	}
	if askBeforeInstall {
		allowInstall, err := conn.getPermissionToInstallWsh(ctx, clientDisplayName)
		if err != nil {
			log.Printf("error getting permission to install wsh: %v\n", err)
			return WshCheckResult{NoWshReason: "error getting user permission to install", WshError: err}
		}
		if !allowInstall {
			return WshCheckResult{NoWshReason: "user selected not to install wsh extensions"}
		}
	}
	err := conn.OpenDomainSocketListener(ctx)
	if err != nil {
		conn.Infof(ctx, "ERROR opening domain socket listener: %v\n", err)
		err = fmt.Errorf("error opening domain socket listener: %w", err)
		return WshCheckResult{NoWshReason: "error opening domain socket", WshError: err}
	}
	needsInstall, clientVersion, osArchStr, err := conn.StartConnServer(ctx, false)
	if err != nil {
		conn.Infof(ctx, "ERROR starting conn server: %v\n", err)
		err = fmt.Errorf("error starting conn server: %w", err)
		return WshCheckResult{NoWshReason: "error starting connserver", WshError: err}
	}
	if needsInstall {
		conn.Infof(ctx, "connserver needs to be (re)installed\n")
		err = conn.InstallWsh(ctx, osArchStr)
		if err != nil {
			conn.Infof(ctx, "ERROR installing wsh: %v\n", err)
			err = fmt.Errorf("error installing wsh: %w", err)
			return WshCheckResult{NoWshReason: "error installing wsh/connserver", WshError: err}
		}
		needsInstall, clientVersion, _, err = conn.StartConnServer(ctx, true)
		if err != nil {

View on GitHub (pinned to a4447c1563)

Solutions

1. Inspect the wrapped error (%w) to find the underlying syscall failure (mkdir, bind, chmod)
2. Remove stale socket files in ~/.wsh inside the WSL distro and reconnect
3. Verify the distro's filesystem is writable and the user owns their home directory
4. Fully restart the WSL distro (wsl --shutdown) to clear stale state
5. Update wsh: run 'wsh upgrade' inside the distro

Example fix

// before
res, err := wshrpc.DoWshEnableCommand(connName) // surfaces 'error opening domain socket listener: ...'
// after
// run inside distro first: rm -f ~/.wsh/*.sock && wsl --shutdown
res, err := wshrpc.DoWshEnableCommand(connName)

// check distro is reachable and home is writable first
if err := exec.Command("wsl", "-d", distro, "--", "bash", "-c", "touch ~/.wsh_probe && rm ~/.wsh_probe").Run(); err != nil {
    return fmt.Errorf("distro home not writable: %w", err)
}

res, err := tryEnableWsh(ctx, conn)
if err != nil && errors.Is(err, baseErr) && strings.Contains(err.Error(), "domain socket listener") {
    // clean stale sockets then retry once
    exec.Command("wsl", "-d", distro, "--", "bash", "-c", "rm -f ~/.wsh/*.sock").Run()
    res, err = tryEnableWsh(ctx, conn)
}

When it happens

Trigger: OpenDomainSocketListener fails during connectInternal — typically because the ~/.wsh directory/socket path cannot be created in the distro, the socket already exists from a stale run, or the distro's filesystem/permissions block socket creation.

Common situations: Read-only or full WSL filesystem, stale socket file from a previous crashed session, WSL distro not fully booted, mismatched user permissions after changing WSL user.

Related errors

• cannot open local file %s: %w
• SwapToken is required in CommandOptsType
• unable to obtain client info: %w
• error starting conn server: %w
• error installing wsh: %w

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