{"record":{"id":"40499df2c320b3d7","repo":"thanos-io/thanos","slug":"error-starting-web-server","errorCode":null,"errorMessage":"error starting web server","messagePattern":"error starting web server","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/thanos/receive.go","lineNumber":495,"sourceCode":"\t\t\tfunc() error {\n\t\t\t\tlevel.Info(logger).Log(\"msg\", \"listening for StoreAPI and WritableStoreAPI gRPC\", \"address\", conf.grpcConfig.bindAddress)\n\t\t\t\tstatusProber.Healthy()\n\t\t\t\treturn srv.ListenAndServe()\n\t\t\t},\n\t\t\tfunc(err error) {\n\t\t\t\tstatusProber.NotReady(err)\n\t\t\t\tdefer statusProber.NotHealthy(err)\n\n\t\t\t\tsrv.Shutdown(err)\n\t\t\t},\n\t\t)\n\t}\n\n\tlevel.Debug(logger).Log(\"msg\", \"setting up receive HTTP handler\")\n\t{\n\t\tg.Add(\n\t\t\tfunc() error {\n\t\t\t\treturn errors.Wrap(webHandler.Run(), \"error starting web server\")\n\t\t\t},\n\t\t\tfunc(err error) {\n\t\t\t\twebHandler.Close()\n\t\t\t},\n\t\t)\n\t}\n\n\tif limitsConfig.AreHeadSeriesLimitsConfigured() {\n\t\tlevel.Info(logger).Log(\"msg\", \"setting up periodic (every 15s) meta-monitoring query for limiting cache\")\n\t\t{\n\t\t\tctx, cancel := context.WithCancel(context.Background())\n\t\t\tg.Add(func() error {\n\t\t\t\treturn runutil.Repeat(15*time.Second, ctx.Done(), func() error {\n\t\t\t\t\tif err := limiter.HeadSeriesLimiter().QueryMetaMonitoring(ctx); err != nil {\n\t\t\t\t\t\tlevel.Error(logger).Log(\"msg\", \"failed to query meta-monitoring\", \"err\", err.Error())\n\t\t\t\t\t}\n\t\t\t\t\treturn nil\n\t\t\t\t})","sourceCodeStart":477,"sourceCodeEnd":513,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/cmd/thanos/receive.go#L477-L513","documentation":"runReceive launches the receive HTTP web handler (write path, /api/v1/receive, etc.) in its own goroutine via errgroup. The handler's blocking Run() error (bind failure, listener error, runtime failure) is wrapped with 'error starting web server', which then tears the whole receive process down.","triggerScenarios":"webHandler.Run() fails, most commonly because the configured listen address (--receive.http-address / rw address) is already in use, the address/port is invalid, or the listener errors at runtime.","commonSituations":"Another process (or a second receive replica on the same host) already bound to the port; port 80/1024 restricted for non-root; IPv6 address configured on an IPv4-only host; typo in the address string.","solutions":["Check the wrapped inner error: 'address already in use' means find and stop the conflicting process or change --receive.http-address.","Use ss -ltnp / netstat -ltnp to see what holds the port.","Use a non-privileged port (>1024) or grant the binary NET_BIND_SERVICE capability.","Verify the listen address syntax and that it exists on the host (e.g. 0.0.0.0 vs a specific IP, IPv6 support).","Inspect receive logs for why the web handler failed after startup."],"exampleFix":"// before\nthanos receive --receive.http-address=:19191  # port already taken\n// after\nthanos receive --receive.http-address=:10902","handlingStrategy":"validation","validationCode":"ln, err := net.Listen(\"tcp\", httpAddr)\nif err != nil { return fmt.Errorf(\"cannot bind %s: %w\", httpAddr, err) }\nln.Close() // bind check before starting thanos","typeGuard":null,"tryCatchPattern":"if err := run(); err != nil {\n  if strings.Contains(err.Error(), \"error starting web server\") {\n    if strings.Contains(err.Error(), \"address already in use\") {\n      log.Errorf(\"port conflict on %s; change --receive.http-address\", httpAddr)\n    }\n  }\n}","preventionTips":["Pre-check port availability in entrypoint scripts","Use non-privileged ports (>1024) or NET_BIND_SERVICE capability","Assign unique ports per replica when co-locating processes","Validate listen address syntax and IP family before deployment"],"tags":["http","network","bind","port-in-use","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}