{"record":{"id":"59c3bc38dc426500","repo":"jaegertracing/jaeger","slug":"failed-to-listen-on-grpc-port-w","errorCode":null,"errorMessage":"failed to listen on gRPC port: %w","messagePattern":"failed to listen on gRPC port: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/remote-storage/app/server.go","lineNumber":127,"sourceCode":"\t)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create gRPC server: %w\", err)\n\t}\n\thealthServer := health.NewServer()\n\treflection.Register(server)\n\n\tv2Handler.Register(server, healthServer)\n\tgrpc_health_v1.RegisterHealthServer(server, healthServer)\n\n\treturn server, nil\n}\n\n// Start gRPC server concurrently\nfunc (s *Server) Start(ctx context.Context) error {\n\tvar err error\n\ts.grpcConn, err = s.grpcCfg.NetAddr.Listen(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to listen on gRPC port: %w\", err)\n\t}\n\ts.telset.Logger.Info(\"Starting GRPC server\", zap.Stringer(\"addr\", s.grpcConn.Addr()))\n\ts.stopped.Go(func() {\n\t\tif err := s.grpcServer.Serve(s.grpcConn); err != nil {\n\t\t\ts.telset.Logger.Error(\"GRPC server exited\", zap.Error(err))\n\t\t\ts.telset.ReportStatus(componentstatus.NewFatalErrorEvent(err))\n\t\t}\n\t})\n\n\treturn nil\n}\n\n// Close stops http, GRPC servers and closes the port listener.\nfunc (s *Server) Close() error {\n\ts.grpcServer.Stop()\n\ts.stopped.Wait()\n\ts.telset.ReportStatus(componentstatus.NewEvent(componentstatus.StatusStopped))\n\treturn nil","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/remote-storage/app/server.go#L109-L145","documentation":"This error is wrapped in Server.Start (cmd/remote-storage/app/server.go:127) when s.grpcCfg.NetAddr.Listen(ctx) fails to bind the configured gRPC network address. Start is called at service start to obtain the net.Listener before grpcServer.Serve runs; a failure here means the process cannot accept gRPC connections on the configured endpoint.","triggerScenarios":"Calling Start when the address/port in grpcCfg.NetAddr (e.g. :17271) cannot be bound: port already in use by another process, permission denied on a privileged port (<1024), invalid host/IP in the address, or the context is cancelled before the listener is established.","commonSituations":"Two remote-storage instances started with the same port; a leftover process from a previous run still holding the port in a dev loop; container port conflicts with a sidecar; typo in the host:port config value.","solutions":["Find what holds the port (lsof -i :<port> or ss -ltnp) and stop it, or change the gRPC NetAddr port in the config","Use an unprivileged port (>=1024) or grant capabilities (e.g. NET_BIND_SERVICE in Kubernetes) if a privileged port is required","Correct the NetAddr host:port string; use :0 only if you resolve the actual port via GRPCAddr() after start","Ensure the context passed to Start is not cancelled/expired before Listen completes"],"exampleFix":"// before (config)\n// grpc:\n//   endpoint: :17271   # already in use by another instance\n// after\n// grpc:\n//   endpoint: :17272   # free port, or kill the duplicate process first","handlingStrategy":"validation","validationCode":"// before Start, probe the port\naddr := s.grpcCfg.NetAddr.Endpoint\nln, err := net.Listen(\"tcp\", addr)\nif err != nil {\n\treturn fmt.Errorf(\"gRPC port %s unavailable: %w\", addr, err)\n}\nln.Close() // let Start bind it for real","typeGuard":null,"tryCatchPattern":"if err := srv.Start(ctx); err != nil {\n\tif errors.Is(err, syscall.EADDRINUSE) {\n\t\tlog.Fatalf(\"gRPC endpoint %s already in use; stop the other process or change the port\", srv.GRPCAddr())\n\t}\n\treturn err\n}","preventionTips":["Use distinct ports per component/instance in shared dev environments; use :0 plus GRPCAddr() for tests","Add liveness checks (grpc_health_v1) so port conflicts surface immediately","Clean up stale processes before re-running locally (pkill or docker rm of the prior run)","Prefer capabilities or unprivileged ports over running as root to bind privileged ports"],"tags":["grpc","network","port-bind","address-in-use"],"backgroundTag":"address-already-in-use","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}