wavetermdev/waveterm · error

error setting up connserver rpc client: %v

Error message

error setting up connserver rpc client: %v

What it means

Returned by serverRunRouter when setupConnServerRpcClientWithRouter fails to establish the RPC client to the connserver over the local domain socket. Without this client the router cannot proxy calls, so startup aborts. The underlying cause is wrapped with %v.

Source

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

		defer func() {
			panichandler.PanicHandler("serverRunRouter:drainRawCh", recover())
		}()
		defer func() {
			log.Printf("stdin closed, shutting down")
			wshutil.DoShutdown("", 0, true)
		}()
		for range rawCh {
			// ignore
		}
	}()
	router.RegisterUpstream(termProxy)

	sockName := getRemoteDomainSocketName()

	// setup the connserver rpc client first
	client, bareRouteId, err := setupConnServerRpcClientWithRouter(router, sockName)
	if err != nil {
		return fmt.Errorf("error setting up connserver rpc client: %v", err)
	}
	wshfs.RpcClient = client
	wshfs.RpcClientRouteId = bareRouteId

	log.Printf("trying to get JWT public key")

	// fetch and set JWT public key
	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)

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the connserver is running and the domain socket exists at getRemoteDomainSocketName()
2. Remove stale socket files and restart both the connserver and the router
3. Check socket file permissions (should be 0700 and owned by the same user)
4. Read the wrapped inner error for the exact handshake/connect failure and align wsh versions on both sides

Example fix

// before
client, bareRouteId, err := setupConnServerRpcClientWithRouter(router, sockName)
if err != nil {
    return fmt.Errorf("error setting up connserver rpc client: %v", err)
}
// after
client, bareRouteId, err := setupConnServerRpcClientWithRouter(router, sockName)
if err != nil {
    if _, statErr := os.Stat(sockName); os.IsNotExist(statErr) {
        return fmt.Errorf("connserver socket %s not found; is connserver running? underlying: %v", sockName, err)
    }
    return fmt.Errorf("error setting up connserver rpc client: %v", err)
}

if _, err := os.Stat(sockName); err != nil {
    return fmt.Errorf("connserver socket %s not available yet: %w", sockName, err)
}

var client *wshclient.WshClient
var bareRouteId string
var err error
for i := 0; i < 5; i++ {
    client, bareRouteId, err = setupConnServerRpcClientWithRouter(router, sockName)
    if err == nil {
        break
    }
    time.Sleep(1 << i * 100 * time.Millisecond)
}
if err != nil {
    return fmt.Errorf("error setting up connserver rpc client: %v", err)
}

When it happens

Trigger: The domain socket does not exist yet (connserver not started or crashed), permissions on the socket block connect, or the RPC handshake/route registration with the connserver fails.

Common situations: Starting `wsh server` before the connserver is up, stale socket file left behind by a crashed process, mismatched versions between wsh client and connserver, sandboxed environments restricting unix socket connections.

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

• watching pid: %v
• getting ssh connection status: %w
• connecting connection: %w
• error getting jwt public key: %v
• no route id available

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