wavetermdev/waveterm · critical

error connecting to domain socket %s: %v

Error message

error connecting to domain socket %s: %v

What it means

After extracting the socket name from the JWT, serverRunRouterDomainSocket dials the upstream unix domain socket with net.Dial("unix", sockName). This error wraps that dial failure, meaning nothing is listening at the path, the socket file is stale, or the process lacks permission to connect.

Source

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

	startJobLogCleanup()
	log.Printf("running server, successfully started")
	select {}
}

func serverRunRouterDomainSocket(jwtToken string) error {
	log.Printf("starting connserver router (domain socket upstream)")

	// extract socket name from JWT token (unverified - we're on the client side)
	sockName, err := wshutil.ExtractUnverifiedSocketName(jwtToken)
	if err != nil {
		return fmt.Errorf("error extracting socket name from JWT: %v", err)
	}

	// connect to the forwarded domain socket
	sockName = wavebase.ExpandHomeDirSafe(sockName)
	conn, err := net.Dial("unix", sockName)
	if err != nil {
		return fmt.Errorf("error connecting to domain socket %s: %v", sockName, err)
	}

	// create router
	router := wshutil.NewWshRouter()
	ConnServerWshRouter = router

	// create proxy for the domain socket connection
	upstreamProxy := wshutil.MakeRpcProxy("connserver-upstream")

	// goroutine to write to the domain socket
	go func() {
		defer func() {
			panichandler.PanicHandler("serverRunRouterDomainSocket:WriteLoop", recover())
		}()
		writeErr := wshutil.AdaptOutputChToStream(upstreamProxy.ToRemoteCh, conn)
		if writeErr != nil {
			log.Printf("error writing to upstream domain socket: %v\n", writeErr)
		}

View on GitHub (pinned to a4447c1563)

Solutions

1. Confirm the Wave server is running and the socket file exists at the printed path (ls -l <sockName>).
2. Remove a stale socket file and restart the Wave server so it rebinds.
3. Check socket directory permissions (read/write/execute for your user).
4. Verify the socket path after ExpandHomeDirSafe points at the current session's socket, not a previous one.
5. If on WSL or a network mount, run the server and client on a filesystem supporting unix sockets.

Example fix

// before
sockName = wavebase.ExpandHomeDirSafe(sockName)
conn, err := net.Dial("unix", sockName)
if err != nil {
	return fmt.Errorf("error connecting to domain socket %s: %v", sockName, err)
}
// after
sockName = wavebase.ExpandHomeDirSafe(sockName)
if fi, err := os.Stat(sockName); err != nil {
	return fmt.Errorf("upstream socket %s does not exist (is the server running?): %w", sockName, err)
} else if fi.Mode()&os.ModeSocket == 0 {
	return fmt.Errorf("path %s is not a socket (stale file); remove it and restart the server", sockName)
}
conn, err := net.Dial("unix", sockName)
if err != nil {
	return fmt.Errorf("error connecting to domain socket %s: %w", sockName, err)
}

sockName = wavebase.ExpandHomeDirSafe(sockName)
if fi, err := os.Stat(sockName); err != nil {
	return fmt.Errorf("socket %s missing: %w", sockName, err)
} else if fi.Mode()&os.ModeSocket == 0 {
	return fmt.Errorf("%s is not a socket", sockName)
}

conn, err := net.Dial("unix", sockName)
if err != nil {
	return fmt.Errorf("error connecting to domain socket %s: %w", sockName, err)
}
defer conn.Close()

When it happens

Trigger: net.Dial("unix", expandedSockName) fails inside serverRunRouterDomainSocket — e.g. the Wave server is not running, the socket was deleted, or permissions block access.

Common situations: Wave terminal server crashed leaving a dead socket file; connecting to a socket in another user's home (permission denied); WSL/network-mount filesystems where unix sockets don't work; typo'd or stale WAVETERM env vars pointing at an old session's socket.

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

• cannot create unix listener: %v
• error creating listener at %v: %v
• failed to listen on domain socket: %w
• unable to request connection domain socket: %v
• error setting up domain socket rpc client: %v

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