thanos-io/thanos · error

no external labels configured for receive, uniquely…

Error message

no external labels configured for receive, uniquely identifying external labels must be configured (ideally with `receive_` prefix); see https://thanos.io/tip/thanos/storage.md#external-labels for details.

What it means

Error "no external labels configured for receive, uniquely identifying external labels must be configured (ideally with `receive_` prefix); see https://thanos.io/tip/thanos/storage.md#external-labels for details." thrown in thanos-io/thanos.

Solutions

1. Configure external labels via --label, e.g. --label=receive_replica=$(HOSTNAME)
2. Ensure labels uniquely identify this receive instance and ideally use the receive_ prefix
3. See the Thanos storage.md external labels docs

When it happens

Trigger: Thrown at cmd/thanos/receive.go:82 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/5acac03339b0df25. Report an issue: GitHub.

Appendix: source

Thrown at cmd/thanos/receive.go:82

)

func registerReceive(app *extkingpin.App) {
	cmd := app.Command(component.Receive.String(), "Accept Prometheus remote write API requests and write to local tsdb.")

	conf := &receiveConfig{}
	conf.registerFlag(cmd)

	cmd.Setup(func(g *run.Group, logger log.Logger, reg *prometheus.Registry, tracer opentracing.Tracer, _ <-chan struct{}, debugLogging bool) error {
		lset, err := parseFlagLabels(conf.labelStrs)
		if err != nil {
			return errors.Wrap(err, "parse labels")
		}

		if !model.UTF8Validation.IsValidLabelName(conf.tenantLabelName) {
			return errors.Errorf("unsupported format for tenant label name, got %s", conf.tenantLabelName)
		}
		if lset.Len() == 0 {
			return errors.New("no external labels configured for receive, uniquely identifying external labels must be configured (ideally with `receive_` prefix); see https://thanos.io/tip/thanos/storage.md#external-labels for details.")
		}

		grpcLogOpts, logFilterMethods, err := logging.ParsegRPCOptions(conf.reqLogConfig)

		if err != nil {
			return errors.Wrap(err, "error while parsing config for request logging")
		}

		tsdbOpts := &tsdb.Options{
			MinBlockDuration:               int64(time.Duration(*conf.tsdbMinBlockDuration) / time.Millisecond),
			MaxBlockDuration:               int64(time.Duration(*conf.tsdbMaxBlockDuration) / time.Millisecond),
			RetentionDuration:              int64(time.Duration(*conf.retention) / time.Millisecond),
			OutOfOrderTimeWindow:           int64(time.Duration(*conf.tsdbOutOfOrderTimeWindow) / time.Millisecond),
			MaxBytes:                       int64(conf.tsdbMaxBytes),
			OutOfOrderCapMax:               conf.tsdbOutOfOrderCapMax,
			NoLockfile:                     conf.noLockFile,
			WALCompression:                 compressutil.ParseCompressionType(conf.walCompression, compression.Snappy),
			MaxExemplars:                   conf.tsdbMaxExemplars,

View on GitHub (pinned to 35b8b99117)