{"record":{"id":"c042c81a012afd5a","repo":"jaegertracing/jaeger","slug":"query-server-failed-to-initialize-listener-w","errorCode":null,"errorMessage":"query server failed to initialize listener: %w","messagePattern":"query server failed to initialize listener: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/jaeger/internal/extension/jaegerquery/internal/server.go","lineNumber":459,"sourceCode":"\t}\n\n\ts.httpConn, err = s.queryOptions.HTTP.ToListener(ctx)\n\tif err != nil {\n\t\treturn err\n\t}\n\ts.telset.Logger.Info(\n\t\t\"Query server started\",\n\t\tzap.String(\"http_addr\", s.HTTPAddr()),\n\t\tzap.String(\"grpc_addr\", s.GRPCAddr()),\n\t)\n\treturn nil\n}\n\n// Start http and gRPC servers concurrently\nfunc (s *Server) Start(ctx context.Context) error {\n\terr := s.initListener(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"query server failed to initialize listener: %w\", err)\n\t}\n\n\tvar httpPort int\n\tif port, err := getPortForAddr(s.httpConn.Addr()); err == nil {\n\t\thttpPort = port\n\t}\n\n\tvar grpcPort int\n\tif port, err := getPortForAddr(s.grpcConn.Addr()); err == nil {\n\t\tgrpcPort = port\n\t}\n\n\ts.bgFinished.Go(func() {\n\t\ts.telset.Logger.Info(\"Starting HTTP server\", zap.Int(\"port\", httpPort), zap.String(\"addr\", s.queryOptions.HTTP.NetAddr.Endpoint))\n\t\terr := s.httpServer.Serve(s.httpConn)\n\t\tif err != nil && !errors.Is(err, http.ErrServerClosed) {\n\t\t\ts.telset.Logger.Error(\"Could not start HTTP server\", zap.Error(err))\n\t\t\ts.telset.ReportStatus(componentstatus.NewFatalErrorEvent(err))","sourceCodeStart":441,"sourceCodeEnd":477,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/extension/jaegerquery/internal/server.go#L441-L477","documentation":"Server.Start brings up both the HTTP and gRPC query servers, and it first calls initListener to bind the configured ports. If the listener cannot be created — the OS refuses the bind — Start returns this wrapped error immediately so the extension fails fast instead of serving on a broken socket.","triggerScenarios":"Calling Server.Start (via the extension's Start) when initListener fails: the configured HTTP/gRPC port is already bound by another process, the port number is out of the valid range (e.g. 0 not allowed for this listener, or > 65535), or the process lacks permission to bind (privileged port without capabilities).","commonSituations":"Two jaeger-query instances pointed at the same ports; a leftover development process still holding port 16686/16685; docker port-mapping conflicts; config where the port was left blank or mistyped so it resolves to an invalid address; running in a container as non-root while binding port < 1024.","solutions":["Check the wrapped inner error: 'address already in use' means find and stop the other process (lsof -i :16686) or change --query.http-server / grpc-server ports","Verify the configured port values in the config file/flags are valid numbers within 1-65535 and the host address is resolvable","If binding a privileged port, run with the required capability or move to an unprivileged port","Wait for a previous instance to fully shut down (Close releases the listener) before starting a new one on the same ports"],"exampleFix":"// before: port already taken by a stale process\njaeger-query --query.http-server.host-port=:16686  # Error: listen tcp :16686: bind: address already in use\n// after\nkill <stale-pid> && jaeger-query --query.http-server.host-port=:16686","handlingStrategy":"retry","validationCode":"// check the port is free before starting the server\nfunc portFree(addr string) bool {\n\tln, err := net.Listen(\"tcp\", addr)\n\tif err != nil {\n\t\treturn false\n\t}\n\tln.Close()\n\treturn true\n}","typeGuard":null,"tryCatchPattern":"err := server.Start(ctx)\nif err != nil {\n\tif errors.Is(err, syscall.EADDRINUSE) || strings.Contains(err.Error(), \"address already in use\") {\n\t\t// pick another port or abort startup with a clear message\n\t\tlog.Fatalf(\"query port already in use: %v\", err)\n\t}\n\treturn fmt.Errorf(\"starting query server: %w\", err)\n}","preventionTips":["Reserve fixed, documented ports for jaeger-query (default 16686 HTTP, 16685 gRPC) and avoid running other services on them","Use SO_REUSEPORT or an ephemeral port in dev environments to avoid clashes","In containers/Kubernetes, let the orchestrator assign host ports instead of hardcoding them","Gracefully stop previous instances (Server.Close) before restarting on the same ports"],"tags":["network","startup","port-binding","grpc","http"],"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"}