thanos-io/thanos · error

unsupported format for label

Error message

unsupported format for label %s

What it means

After splitting on the first '=', parseFlagLabels validates the label name with model.UTF8Validation.IsValidLabelName. If the key part is not a valid Prometheus label name (e.g. starts with a digit, contains illegal characters, or is empty like "=value"), this error is returned. It guards against label names the TSDB/StoreAPI cannot accept.

Solutions

1. Rename the label to a valid name: letters/underscores first, then alphanumerics/underscores, e.g. my-label=x -> my_label=x.
2. Escape or replace illegal characters in the key (hyphens to underscores).
3. Ensure the key is non-empty: "=x" is invalid; supply a real label name before '='.

Example fix

// before
thanos sidecar --label cluster-name=eu1
// after
thanos sidecar --label cluster_name=eu1

import "github.com/prometheus/common/model"
func validLabelName(l string) bool {
    parts := strings.SplitN(l, "=", 2)
    return len(parts) == 2 && model.UTF8Validation.IsValidLabelName(parts[0])
}

// Go
if _, err := parseFlagLabels(args); err != nil {
    if strings.HasPrefix(err.Error(), "unsupported format for label") {
        // fix label name before retrying
    }
}

When it happens

Trigger: Passing a label whose key violates Prometheus label name rules: "1abc=x", "my-label=x" (hyphen), ".bad=x", or an empty name "=x".

Common situations: Users unaware that label names must match [a-zA-Z_][a-zA-Z0-9_]* (legacy) or the stricter UTF-8 rules; using DNS hostnames with hyphens as label names; typo leaving an empty key after quoting issues.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• unrecognized label
• unquote label value
• --auto-gomemlimit.ratio must be greater than 0 and less…
• error validating the config
• parse labels

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

Appendix: source

Thrown at cmd/thanos/config.go:335

		Default("30s").DurationVar(&ac.alertmgrsDNSSDInterval)
	ac.alertQueryURL = cmd.Flag("alert.query-url", "The external Thanos Query URL that would be set in all alerts 'Source' field").String()
	cmd.Flag("alert.label-drop", "Labels by name to drop before sending to alertmanager. This allows alert to be deduplicated on replica label (repeated). Similar Prometheus alert relabelling").
		StringsVar(&ac.alertExcludeLabels)
	ac.alertRelabelConfigPath = extflag.RegisterPathOrContent(cmd, "alert.relabel-config", "YAML file that contains alert relabelling configuration.", extflag.WithEnvSubstitution())
	ac.alertSourceTemplate = cmd.Flag("alert.query-template", "Template to use in alerts source field. Need only include {{.Expr}} parameter").Default("/graph?g0.expr={{.Expr}}&g0.tab=1").String()

	return ac
}

func parseFlagLabels(s []string) (labels.Labels, error) {
	var lset labels.ScratchBuilder
	for _, l := range s {
		parts := strings.SplitN(l, "=", 2)
		if len(parts) != 2 {
			return labels.EmptyLabels(), errors.Errorf("unrecognized label %q", l)
		}
		if !model.UTF8Validation.IsValidLabelName(parts[0]) {
			return labels.EmptyLabels(), errors.Errorf("unsupported format for label %s", l)
		}
		val, err := strconv.Unquote(parts[1])
		if err != nil {
			return labels.EmptyLabels(), errors.Wrap(err, "unquote label value")
		}
		lset.Add(parts[0], val)
	}
	lset.Sort()
	return lset.Labels(), nil
}

type goMemLimitConfig struct {
	enableAutoGoMemlimit bool
	memlimitRatio        float64
}

func (gml *goMemLimitConfig) registerFlag(cmd extkingpin.FlagClause) *goMemLimitConfig {
	cmd.Flag("enable-auto-gomemlimit",

View on GitHub (pinned to 35b8b99117)