Field [%s]: Buckets should only be defined for Timer and His

Error message

Field [%s]: Buckets should only be defined for Timer and Histogram metric types

What it means

metrics.Init() only applies a `buckets` tag to *Timer and *Histogram fields; for any other metric type (Counter, Gauge, etc.) the presence of a buckets tag is a configuration mistake and returns this error naming the field. Buckets have no meaning for counters and gauges, so the library refuses rather than ignoring them.

Source

Thrown at internal/metrics/metrics.go:96

							field.Name, bucket, bucketString,
						)
					}
					timerBuckets = append(timerBuckets, d)
				}
			case field.Type.AssignableTo(histogramPtrType):
				bucketValues := strings.Split(bucketString, ",")
				for _, bucket := range bucketValues {
					b, err := strconv.ParseFloat(bucket, 64)
					if err != nil {
						return fmt.Errorf(
							"Field [%s]: Bucket [%s] could not be converted to float64 in 'buckets' string [%s]",
							field.Name, bucket, bucketString,
						)
					}
					histogramBuckets = append(histogramBuckets, b)
				}
			default:
				return fmt.Errorf(
					"Field [%s]: Buckets should only be defined for Timer and Histogram metric types",
					field.Name,
				)
			}
		}
		help := field.Tag.Get("help")
		var obj any
		switch {
		case field.Type.AssignableTo(counterPtrType):
			obj = factory.Counter(Options{
				Name: metric,
				Tags: tags,
				Help: help,
			})
		case field.Type.AssignableTo(gaugePtrType):
			obj = factory.Gauge(Options{
				Name: metric,
				Tags: tags,

View on GitHub (pinned to 806f444784)

Solutions

Remove the buckets tag from the offending non-timer/histogram field
If buckets are needed, change the field type to *Timer or *Histogram
Double-check the field's pointer type matches the intended metric kind

Example fix

// before
Total *Counter `metric:"total" buckets:"1,2,3"`
// after
Total *Counter `metric:"total"`

Defensive patterns

Strategy: validation

Validate before calling

func bucketsAllowed(t reflect.Type) bool {
    return reflect.PointerTo(timerType) == t || reflect.PointerTo(histogramType) == t
}

Try / catch

if err := metrics.Init(&m); err != nil {
    if strings.Contains(err.Error(), "only be defined for Timer and Histogram") {
        // drop the buckets tag or change the field type
    }
    return err
}

Prevention

Only add buckets tags to *Timer and *Histogram fields
Remove buckets when converting a histogram/timer to counter/gauge
Review full tag lines when copy-pasting between metric kinds
Add a test that Initializes every metrics struct in the codebase

When it happens

Trigger: A *Counter or *Gauge (or any non-timer/histogram field) declaring `buckets:"..."` in its struct tag when Init/MustInit runs.

Common situations: Copy-pasting a full tag line from a timer/histogram field onto a counter; converting a Histogram field to a Counter without removing its buckets tag.

Related errors

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/0d947abcbc70fe0a. Report an issue: GitHub.