thanos-io/thanos · error

--receive.lazy-retrieval-max-buffered-responses must be > 0

Error message

--receive.lazy-retrieval-max-buffered-responses must be > 0

What it means

runReceive enforces that the flag --receive.lazy-retrieval-max-buffered-responses is strictly positive before enabling lazy retrieval proxy options. If the value is <= 0, it returns a plain errors.New('Not ready'... actually '--receive.lazy-retrieval-max-buffered-responses must be > 0') and receive exits at startup. This guard prevents configuring the ProxyStore with a non-positive buffered response limit, which would break lazy retrieval backpressure.

Solutions

1. Set --receive.lazy-retrieval-max-buffered-responses to a positive integer (e.g. 1000) on the command line or in your manifest.
2. Check the templating/automation that renders the flag for empty or negative values.
3. To disable lazy retrieval, remove the lazy-retrieval related flags instead of setting the buffer to 0.

Example fix

// before
--receive.lazy-retrieval-max-buffered-responses=0
// after
--receive.lazy-retrieval-max-buffered-responses=1000

if v, err := strconv.Atoi(flagValue); err != nil || v <= 0 {
  return fmt.Errorf("--receive.lazy-retrieval-max-buffered-responses must be > 0, got %q", flagValue)
}

When it happens

Trigger: Launching `thanos receive` with --receive.lazy-retrieval-max-buffered-responses set to 0, a negative number, or an unparseable value that left the config field at/negatives zero while lazy retrieval options are being wired into the ProxyStore.

Common situations: Operator set the flag to 0 intending to 'disable' lazy retrieval; an automation template rendered an empty or negative value; copy-paste from docs of a different flag.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• parse limit configuration
• unsupported format for label
• --auto-gomemlimit.ratio must be greater than 0 and less…
• preparing command failed
• error validating the config

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

Appendix: source

Thrown at cmd/thanos/receive.go:366

			statusProber.Healthy()
			return srv.ListenAndServe()
		}, func(err error) {
			statusProber.NotReady(err)
			defer statusProber.NotHealthy(err)

			srv.Shutdown(err)
		})
	}

	level.Debug(logger).Log("msg", "setting up gRPC server")
	{
		tlsCfg, err := tls.NewServerConfig(log.With(logger, "protocol", "gRPC"), conf.grpcConfig.tlsSrvCert, conf.grpcConfig.tlsSrvKey, conf.grpcConfig.tlsSrvClientCA, conf.grpcConfig.tlsMinVersion, conf.grpcConfig.tlsCiphers, conf.grpcConfig.tlsCurves)
		if err != nil {
			return errors.Wrap(err, "setup gRPC server")
		}

		if conf.lazyRetrievalMaxBufferedResponses <= 0 {
			return errors.New("--receive.lazy-retrieval-max-buffered-responses must be > 0")
		}
		options := []store.ProxyStoreOption{
			store.WithProxyStoreDebugLogging(debugLogging),
			store.WithMatcherCache(cache),
			store.WithoutDedup(),
			store.WithLazyRetrievalMaxBufferedResponsesForProxy(conf.lazyRetrievalMaxBufferedResponses),
		}

		proxy := store.NewProxyStore(
			logger,
			reg,
			dbs.TSDBLocalClients,
			comp,
			labels.Labels{},
			0,
			store.LazyRetrieval,
			options...,
		)

View on GitHub (pinned to 35b8b99117)