wavetermdev/waveterm · critical

cannot create unix listener: %v

Error message

cannot create unix listener: %v

What it means

serverRunRouter wraps the error from MakeRemoteUnixListener, which creates the local unix domain socket that wsh clients connect to. Failure means the socket path could not be created/bound — typically a stale socket file, permission problems, or a path that is too long or on an unsuitable filesystem. Without this listener no local wsh commands can reach the connserver.

Source

Thrown at cmd/wsh/cmd/wshcmd-connserver.go:267

	jwtPublicKeyB64, err := wshclient.GetJwtPublicKeyCommand(client, nil)
	if err != nil {
		return fmt.Errorf("error getting jwt public key: %v", err)
	}
	jwtPublicKeyBytes, err := base64.StdEncoding.DecodeString(jwtPublicKeyB64)
	if err != nil {
		return fmt.Errorf("error decoding jwt public key: %v", err)
	}
	err = wavejwt.SetPublicKey(jwtPublicKeyBytes)
	if err != nil {
		return fmt.Errorf("error setting jwt public key: %v", err)
	}

	log.Printf("got JWT public key")

	// now set up the domain socket
	unixListener, err := MakeRemoteUnixListener()
	if err != nil {
		return fmt.Errorf("cannot create unix listener: %v", err)
	}
	log.Printf("unix listener started")
	go func() {
		defer func() {
			panichandler.PanicHandler("serverRunRouter:runListener", recover())
		}()
		runListener(unixListener, router)
	}()
	// run the sysinfo loop
	go func() {
		defer func() {
			panichandler.PanicHandler("serverRunRouter:RunSysInfoLoop", recover())
		}()
		wshremote.RunSysInfoLoop(client, connServerConnName)
	}()
	startJobLogCleanup()
	log.Printf("running server, successfully started")
	select {}

View on GitHub (pinned to a4447c1563)

Solutions

1. Remove any stale socket file at the path MakeRemoteUnixListener uses, then retry.
2. Verify the parent directory exists and is writable by the current user.
3. Check TMPDIR/env overrides and socket path length (< ~104 chars on macOS).
4. Confirm the filesystem supports unix sockets; move the socket dir if on a network mount.
5. Check the wrapped %v for 'address already in use' vs 'permission denied' to target the fix.

Example fix

// before
unixListener, err := MakeRemoteUnixListener()
if err != nil {
	return fmt.Errorf("cannot create unix listener: %v", err)
}
// after
sockPath := getRemoteDomainSocketName()
if fi, err := os.Stat(sockPath); err == nil && fi.Mode()&os.ModeSocket != 0 {
	os.Remove(sockPath) // clear stale socket from a previous run
}
unixListener, err := MakeRemoteUnixListener()
if err != nil {
	return fmt.Errorf("cannot create unix listener %s: %w", sockPath, err)
}

sockPath := getRemoteDomainSocketName()
if fi, err := os.Stat(sockPath); err == nil && fi.Mode()&os.ModeSocket != 0 {
	os.Remove(sockPath)
}
if err := os.MkdirAll(filepath.Dir(sockPath), 0o700); err != nil {
	return err
}

unixListener, err := MakeRemoteUnixListener()
if err != nil {
	return fmt.Errorf("cannot create unix listener: %w", err)
}
defer unixListener.Close()

When it happens

Trigger: serverRunRouter calls MakeRemoteUnixListener() after setting the JWT public key; the underlying net.Listen("unix", path) fails.

Common situations: Leftover socket file from a previous crashed run; running in a container/home dir with wrong permissions; TMPDIR pointing to a nonexistent or full path; filesystem that does not support unix sockets (some network mounts).

Related errors

• error creating listener at %v: %v
• error connecting to domain socket %s: %v
• failed to create socket directory: %w
• failed to listen on domain socket: %w
• unable to request connection domain socket: %v

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