{"record":{"id":"b289e3a0ee4c3061","repo":"openimsdk/open-im-server","slug":"listen-rpc-s-s-w","errorCode":null,"errorMessage":"listen rpc %s %s %w","messagePattern":"listen rpc (.+?) (.+?) %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/common/startrpc/start.go","lineNumber":229,"sourceCode":"\tonGrpcServiceRegistrar := func(desc *grpc.ServiceDesc, impl any) {\n\t\tif rpcServer != nil {\n\t\t\trpcServer.RegisterService(desc, impl)\n\t\t\treturn\n\t\t}\n\t\tvar rpcListenAddr string\n\t\tif autoSetPorts {\n\t\t\trpcListenAddr = net.JoinHostPort(listenIP, \"0\")\n\t\t} else {\n\t\t\trpcPort, err := datautil.GetElemByIndex(rpcPorts, index)\n\t\t\tif err != nil {\n\t\t\t\tcancel(fmt.Errorf(\"rpcPorts index out of range %s %w\", rpcRegisterName, err))\n\t\t\t\treturn\n\t\t\t}\n\t\t\trpcListenAddr = net.JoinHostPort(listenIP, strconv.Itoa(rpcPort))\n\t\t}\n\t\trpcListener, err := net.Listen(\"tcp\", rpcListenAddr)\n\t\tif err != nil {\n\t\t\tcancel(fmt.Errorf(\"listen rpc %s %s %w\", rpcRegisterName, rpcListenAddr, err))\n\t\t\treturn\n\t\t}\n\n\t\trpcServer = grpc.NewServer(options...)\n\t\trpcServer.RegisterService(desc, impl)\n\t\trpcGracefulStop = make(chan struct{})\n\t\trpcPort := rpcListener.Addr().(*net.TCPAddr).Port\n\t\tlog.ZDebug(ctx, \"rpc start register\", \"rpcRegisterName\", rpcRegisterName, \"registerIP\", registerIP, \"rpcPort\", rpcPort)\n\t\tgrpcOpt := grpc.WithTransportCredentials(insecure.NewCredentials())\n\t\trpcGracefulStop = make(chan struct{})\n\t\tgo func() {\n\t\t\t<-ctx.Done()\n\t\t\trpcServer.GracefulStop()\n\t\t\tclose(rpcGracefulStop)\n\t\t}()\n\t\tif err := client.Register(ctx, rpcRegisterName, registerIP, rpcListener.Addr().(*net.TCPAddr).Port, grpcOpt); err != nil {\n\t\t\tcancel(fmt.Errorf(\"rpc register %s %w\", rpcRegisterName, err))\n\t\t\treturn","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/openimsdk/open-im-server/blob/175a7bb0673eca18e9d1b10bff4f728da6b1b513/pkg/common/startrpc/start.go#L211-L247","documentation":"The RPC server failed to bind its TCP listener on rpcListenAddr. net.Listen returned an error and startup is cancelled with 'listen rpc <name> <addr>'. It means the address/port could not be opened for the gRPC server.","triggerScenarios":"net.Listen(\"tcp\", rpcListenAddr) fails — typically because the port is already bound by another process, the IP is not assigned to the host, or the port is privileged/not permitted.","commonSituations":"Two services configured with the same port in rpcPorts; stale process still holding the port; listenIP set to an interface that doesn't exist in containers/K8s; port below 1024 without privileges.","solutions":["Check what holds the port (ss -ltnp / lsof -i) and stop the conflicting process or pick a free port","Correct listenIP in config to an IP actually present on the host","Use a port above 1024 or grant the required privileges","Verify rpcPorts values are unique across all services on the host"],"exampleFix":"// before\nrpcPorts: [80, 10120]\n// after\nrpcPorts: [10110, 10120]","handlingStrategy":"try-catch","validationCode":"addr := net.JoinHostPort(listenIP, strconv.Itoa(port))\nif ln, err := net.Listen(\"tcp\", addr); err != nil {\n    return fmt.Errorf(\"port %s unavailable: %w\", addr, err)\n} else { ln.Close() }","typeGuard":null,"tryCatchPattern":"err := startrpc.Start(ctx, cfg)\nvar oe *net.OpError\nif errors.As(err, &oe) && errors.Is(oe.Err, syscall.EADDRINUSE) {\n    // pick another port or abort with a friendly message\n}","preventionTips":["Reserve unique static ports per service per host","Pre-check port availability before start in deploy scripts","Avoid privileged ports unless necessary","Use listenIP 0.0.0.0 or a verified interface IP"],"tags":["network","grpc","bind","ports"],"backgroundTag":"address-already-in-use","analyzedSha":"175a7bb0673eca18e9d1b10bff4f728da6b1b513","analyzedAt":"2026-09-04T16:52:56.821Z","contentChangedAt":"2026-09-04T16:52:56.821Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}