What causes "rpc %s %w" in openimsdk/open-im-server?

Read the wrapped %w cause at the end of the message to find the root failure

rpc %s %w

Error message

rpc %s %w

What it means

Wraps the error returned by rpcFn — the whole RPC startup/serve sequence — as 'rpc <name> <cause>'. This is the outermost wrapper you see when the gRPC server for a given service exits with any error (including the synthesized 'serve end').

Source

Thrown at pkg/common/startrpc/start.go:255

		log.ZDebug(ctx, "rpc start register", "rpcRegisterName", rpcRegisterName, "registerIP", registerIP, "rpcPort", rpcPort)
		grpcOpt := grpc.WithTransportCredentials(insecure.NewCredentials())
		rpcGracefulStop = make(chan struct{})
		go func() {
			<-ctx.Done()
			rpcServer.GracefulStop()
			close(rpcGracefulStop)
		}()
		if err := client.Register(ctx, rpcRegisterName, registerIP, rpcListener.Addr().(*net.TCPAddr).Port, grpcOpt); err != nil {
			cancel(fmt.Errorf("rpc register %s %w", rpcRegisterName, err))
			return
		}

		go func() {
			err := rpcServer.Serve(rpcListener)
			if err == nil {
				err = fmt.Errorf("serve end")
			}
			cancel(fmt.Errorf("rpc %s %w", rpcRegisterName, err))
		}()
	}

	err = rpcFn(ctx, config, client, &grpcServiceRegistrar{onRegisterService: onGrpcServiceRegistrar})
	if err != nil {
		return err
	}
	<-ctx.Done()
	log.ZDebug(ctx, "cmd wait done", "err", context.Cause(ctx))
	if rpcGracefulStop != nil {
		timeout := time.NewTimer(time.Second * 15)
		defer timeout.Stop()
		select {
		case <-timeout.C:
			log.ZWarn(ctx, "rcp graceful stop timeout", nil)
		case <-rpcGracefulStop:
			log.ZDebug(ctx, "rcp graceful stop done")
		}

View on GitHub (pinned to 175a7bb067)

Solutions

Read the wrapped %w cause at the end of the message to find the root failure
Fix the root cause (port conflict, registry connectivity, config)
Check that only one instance per rpcRegisterName/port is running

Defensive patterns

Strategy: try-catch

Try / catch

if err := startrpc.Start(ctx, cfg); err != nil {
    log.Fatalf("rpc startup failed: %v", err) // %w chain reveals root cause
}

Prevention

Always unwrap errors (%w / errors.Unwrap) before diagnosing
Log the full error chain, not just the top wrapper
Run one binary instance per register name/port

When it happens

Trigger: rpcFn returns non-nil after the Serve goroutine cancels the context, propagating the underlying cause (listen failure, register failure, or serve end).

Common situations: Any of the earlier failures (port bind, registration, unexpected serve exit) surfacing at the top level; often seen in process logs as the fatal startup error line.

Related errors

AI-assisted analysis of openimsdk/open-im-server@175a7bb067 (2026-09-04). Data as JSON: /api/errors/e7a1c6d8907fb275. Report an issue: GitHub.