thanos-io/thanos · error

listen gRPC on address

Error message

listen gRPC on address %s

What it means

Raised in grpc.Server.ListenAndServe when net.Listen fails to bind the configured network address (e.g., address already in use, permission denied for privileged ports, invalid address syntax). The gRPC server never starts and the error aborts component startup.

Solutions

1. Check that the configured --grpc-address port is free (address already in use)
2. Verify the address syntax and that the process may bind it (privileged port/permissions)
3. Confirm no other instance of the service is running on the same address

When it happens

Trigger: Thrown at pkg/server/grpc/grpc.go:158 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/de953464a586d22d. Report an issue: GitHub.

Appendix: source

Thrown at pkg/server/grpc/grpc.go:158

	met.InitializeMetrics(s)
	reg.MustRegister(met)

	grpc_health.RegisterHealthServer(s, probe.HealthServer())
	reflection.Register(s)

	return &Server{
		logger: logger,
		comp:   comp,
		srv:    s,
		opts:   options,
	}
}

// ListenAndServe listens on the TCP network address and handles requests on incoming connections.
func (s *Server) ListenAndServe() error {
	l, err := net.Listen(s.opts.network, s.opts.listen)
	if err != nil {
		return errors.Wrapf(err, "listen gRPC on address %s", s.opts.listen)
	}
	s.listener = l

	level.Info(s.logger).Log("msg", "listening for serving gRPC", "address", s.opts.listen)
	return errors.Wrap(s.srv.Serve(s.listener), "serve gRPC")
}

func (s *Server) Address() string {
	if s.listener != nil {
		return s.listener.Addr().String()
	}
	return ""
}

// Shutdown gracefully shuts down the server by waiting,
// for specified amount of time (by gracePeriod) for connections to return to idle and then shut down.
func (s *Server) Shutdown(err error) {
	level.Info(s.logger).Log("msg", "internal server is shutting down", "err", err)

View on GitHub (pinned to 35b8b99117)