What causes "BucketsForCalculation cannot be less than 1" in jaegertracing/jaeger?

Set BucketsForCalculation to at least 1 (e.g. 1 or more buckets covering the calculation interval).

BucketsForCalculation cannot be less than 1

Error message

BucketsForCalculation cannot be less than 1

What it means

errBucketsForCalculation is returned by newPostAggregator when the Configuration's BucketsForCalculation is less than 1. This value defines how many aggregation buckets participate in each calculation, so zero or negative values make the adaptive sampling computation meaningless.

Source

Thrown at internal/sampling/samplingstrategy/adaptive/post_aggregator.go:33

	"github.com/jaegertracing/jaeger/internal/leaderelection"
	"github.com/jaegertracing/jaeger/internal/metrics"
	"github.com/jaegertracing/jaeger/internal/sampling/samplingstrategy/adaptive/calculationstrategy"
	"github.com/jaegertracing/jaeger/internal/storage/v1/api/samplingstore"
	"github.com/jaegertracing/jaeger/internal/storage/v1/api/samplingstore/model"
)

const (
	maxSamplingProbability = 1.0

	getThroughputErrMsg = "failed to get throughput from storage"

	// The number of past entries for samplingCache the leader keeps in memory
	serviceCacheSize = 25
)

var (
	errNonZero               = errors.New("CalculationInterval and AggregationBuckets must be greater than 0")
	errBucketsForCalculation = errors.New("BucketsForCalculation cannot be less than 1")
)

// nested map: service -> operation -> throughput.
type serviceOperationThroughput map[string]map[string]*model.Throughput

func (t serviceOperationThroughput) get(service, operation string) (*model.Throughput, bool) {
	svcThroughput, ok := t[service]
	if ok {
		v, ok := svcThroughput[operation]
		return v, ok
	}
	return nil, false
}

// nested map: service -> operation -> buckets of QPS values.
type serviceOperationQPS map[string]map[string][]float64

type throughputBucket struct {

View on GitHub (pinned to 806f444784)

Solutions

Set BucketsForCalculation to at least 1 (e.g. 1 or more buckets covering the calculation interval).
Verify any env-var/flag mapping that populates BucketsForCalculation defaults to a positive value.
Rely on the standard flag-based configuration to fill sane defaults.

Example fix

// before
conf := &sampling.Config{BucketsForCalculation: 0}
// after
conf := &sampling.Config{BucketsForCalculation: 1, CalculationInterval: 10 * time.Second, AggregationBuckets: 10}

Defensive patterns

Strategy: validation

Validate before calling

if cfg.BucketsForCalculation < 1 {
    return errors.New("BucketsForCalculation cannot be less than 1")
}

Try / catch

agg, err := sampling.NewAggregator(cfg)
if err != nil {
    logger.Fatal("invalid adaptive sampling config", zap.Error(err))
}

Prevention

Set BucketsForCalculation >= 1 in the adaptive sampling config.
Check env parsing that may yield 0 for unset values.
Validate the whole config struct before constructing the aggregator.

When it happens

Trigger: Constructing the adaptive sampling post-aggregator with a Configuration whose BucketsForCalculation is 0 or negative — commonly when the field is omitted in config code or set via an env parse that yields 0.

Common situations: Custom YAML for the adaptive_sampling extension missing BucketsForCalculation; env var parsing returning 0 for an empty value; programmatically zero-valued structs.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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