go-redis/redis · error

redis: at least one metric must be specified for HOTKEYS STA

Error message

redis: at least one metric must be specified for HOTKEYS START

What it means

ErrHotKeysNoMetrics is returned by (*Client).HotKeysStart when args.Metrics is empty (hotkeys_commands.go:64-67). The HOTKEYS START command requires at least one metric to track; the library validates this client-side and sets the error on the returned *StatusCmd without dispatching. Note HOTKEYS is standalone-only (not on Cluster/Ring/Universal).

Source

Thrown at hotkeys_commands.go:54

	// Metrics to track. At least one must be specified.
	Metrics []HotKeysMetric
	// Count is the number of top keys to report.
	// Default: 10, Min: 10, Max: 64
	Count uint8
	// Duration is the auto-stop tracking after this many seconds.
	// Default: 0 (no auto-stop)
	Duration int64
	// Sample is the sample ratio - track keys with probability 1/sample.
	// Default: 1 (track every key), Min: 1
	Sample int64
	// Slots specifies specific hash slots to track (0-16383).
	// All specified slots must be hosted by the receiving node.
	// If not specified, all slots are tracked.
	Slots []uint16
}

// ErrHotKeysNoMetrics is returned when HotKeysStart is called without any metrics specified.
var ErrHotKeysNoMetrics = errors.New("redis: at least one metric must be specified for HOTKEYS START")

// HotKeysStart starts collecting hotkeys data.
// At least one metric must be specified in args.Metrics.
// This command is only available on standalone clients.
func (c *Client) HotKeysStart(ctx context.Context, args *HotKeysStartArgs) *StatusCmd {
	cmdArgs := make([]interface{}, 0, 16)
	cmdArgs = append(cmdArgs, "hotkeys", "start")

	// Validate that at least one metric is specified
	if len(args.Metrics) == 0 {
		cmd := NewStatusCmd(ctx, cmdArgs...)
		cmd.SetErr(ErrHotKeysNoMetrics)
		return cmd
	}

	cmdArgs = append(cmdArgs, "metrics", len(args.Metrics))
	for _, metric := range args.Metrics {
		cmdArgs = append(cmdArgs, strings.ToLower(string(metric)))

View on GitHub (pinned to 36d97525cd)

Solutions

1. Populate args.Metrics with at least redis.HotKeysMetricCPU and/or redis.HotKeysMetricNET.
2. Assert len(args.Metrics) > 0 before calling.

Example fix

// before
client.HotKeysStart(ctx, &redis.HotKeysStartArgs{Count: 20})
// after
client.HotKeysStart(ctx, &redis.HotKeysStartArgs{
    Metrics: []redis.HotKeysMetric{redis.HotKeysMetricCPU, redis.HotKeysMetricNET},
    Count:   20,
})

if len(args.Metrics) == 0 {
    args.Metrics = []redis.HotKeysMetric{redis.HotKeysMetricCPU}
}
client.HotKeysStart(ctx, args)

func validHotKeysArgs(a *redis.HotKeysStartArgs) bool {
    return a != nil && len(a.Metrics) > 0
}

cmd := client.HotKeysStart(ctx, args)
if err := cmd.Err(); errors.Is(err, redis.ErrHotKeysNoMetrics) {
    args.Metrics = []redis.HotKeysMetric{redis.HotKeysMetricCPU}
    cmd = client.HotKeysStart(ctx, args)
}

When it happens

Trigger: Calling client.HotKeysStart(ctx, &HotKeysStartArgs{}) or with Metrics: nil on a *redis.Client.

Common situations: Constructing HotKeysStartArgs with only Count/Duration set and forgetting Metrics, or passing a zero-value struct.

Related errors

• GeoRadius does not support Store or StoreDist
• GeoRadiusStore requires Store or StoreDist
• GeoRadiusByMember does not support Store or StoreDist
• GeoRadiusByMemberStore requires Store or StoreDist
• args should have the same number of keys and vals

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