redis: FILTER_BY_VALUE requires exactly 2 elements [min, max

Error message

redis: FILTER_BY_VALUE requires exactly 2 elements [min, max], got %d

What it means

Returned by appendNRangeOptions when the FilterByValue option is non-empty but does not have exactly two elements. TS.NRANGE/TS.NREVRANGE FILTER_BY_VALUE semantics require a [min, max] pair, so any other length is rejected.

Source

Thrown at timeseries_commands.go:1425

	count int,
	align interface{},
	aggregators [][]Aggregator,
	bucketDuration int,
	bucketTimestamp interface{},
	empty bool,
) ([]interface{}, error) {
	if latest {
		args = append(args, "LATEST")
	}
	if len(filterByTS) > 0 {
		args = append(args, "FILTER_BY_TS")
		for _, ts := range filterByTS {
			args = append(args, ts)
		}
	}
	if len(filterByValue) > 0 {
		if len(filterByValue) != 2 {
			return args, fmt.Errorf("redis: FILTER_BY_VALUE requires exactly 2 elements [min, max], got %d", len(filterByValue))
		}
		args = append(args, "FILTER_BY_VALUE", filterByValue[0], filterByValue[1])
	}
	if count != 0 {
		args = append(args, "COUNT", count)
	}
	if align != nil {
		args = append(args, "ALIGN", align)
	}
	if len(aggregators) > 0 {
		aggParts, err := buildNRangeAggregationArgs(keys, aggregators)
		if err != nil {
			return args, err
		}
		args = append(args, "AGGREGATION")
		for _, a := range aggParts {
			args = append(args, a)
		}

View on GitHub (pinned to 36d97525cd)

Solutions

Pass exactly two values [min, max] in options.FilterByValue.
Leave FilterByValue empty/nil to disable value filtering.
Assert len(FilterByValue) == 0 || len(FilterByValue) == 2 before the call.

Example fix

// before
opts := &redis.TSNRangeOptions{FilterByValue: []float64{1.5}}
client.TSNRangeWithArgs(ctx, keys, 0, -1, opts)

// after
opts := &redis.TSNRangeOptions{FilterByValue: []float64{1.5, 9.5}}
client.TSNRangeWithArgs(ctx, keys, 0, -1, opts)

Defensive patterns

Strategy: validation

Validate before calling

func validateFilterByValue(v []float64) error {
    if len(v) != 0 && len(v) != 2 {
        return fmt.Errorf("FilterByValue must have 2 elements [min,max], got %d", len(v))
    }
    return nil
}

Prevention

Pass FilterByValue as a literal [2]float64 or a two-element slice.
Leave FilterByValue nil to disable value filtering.
Assert the length is 0 or 2 in a shared validator for all TS range options.

When it happens

Trigger: Calling TSNRangeWithArgs/TSNRevRangeWithArgs with options.FilterByValue of length 1 or >=3 (length 0 is allowed and means 'no filter').

Common situations: Passing a single threshold intending min-only filtering, appending min and max separately and missing one, or reusing a slice that holds more than two values.

Related errors

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/2e038f03d1409a41.json. Report an issue: GitHub.