thanos-io/thanos · error

unsupported format for tenant label name, got

Error message

unsupported format for tenant label name, got %s

What it means

The configured tenant label name (via --tenant-label-name) is not a valid Prometheus label name per UTF8Validation. Receive rejects the config because remote-write tenant attribution depends on a syntactically valid label name.

Solutions

1. Set --tenant-label-name to a valid label name (e.g. 'tenant' or '__tenant_id__')
2. Remove unsupported characters from the label name

When it happens

Trigger: Thrown at cmd/thanos/receive.go:79 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/30c49050c9bfeccf. Report an issue: GitHub.

Appendix: source

Thrown at cmd/thanos/receive.go:79

const (
	compressionNone   = "none"
	metricNamesFilter = "metric-names-filter"
)

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,

View on GitHub (pinned to 35b8b99117)