go-redis/redis · error

failed to create connection handoff metric: %w

Error message

failed to create connection handoff metric: %w

What it means

Returned by createRecorder (redisotel.go:241) when meter.Int64Counter fails to create the 'redis.client.connection.handoff' instrument. Only checked when MetricGroupConnectionBasic is enabled.

Source

Thrown at extra/redisotel-native/redisotel.go:241

			return nil, fmt.Errorf("failed to create connection create time histogram: %w", err)
		}
		connectionCreateTime = connectionCreateTimeConv.Inst()

		connectionRelaxedTimeout, err = meter.Int64UpDownCounter(
			MetricConnectionRelaxedTimeout,
			metric.WithDescription("How many times the connection timeout has been increased/decreased (after a server maintenance notification)"),
			metric.WithUnit("{relaxation}"),
		)
		if err != nil {
			return nil, fmt.Errorf("failed to create connection relaxed timeout metric: %w", err)
		}

		connectionHandoff, err = meter.Int64Counter(
			MetricConnectionHandoff,
			metric.WithDescription("Connections that have been handed off to another node (e.g after a MOVING notification)"),
		)
		if err != nil {
			return nil, fmt.Errorf("failed to create connection handoff metric: %w", err)
		}
	}

	var clientErrors metric.Int64Counter
	var maintenanceNotifications metric.Int64Counter

	if cfg.isMetricGroupEnabled(MetricGroupResiliency) {
		clientErrors, err = meter.Int64Counter(
			MetricClientErrors,
			metric.WithDescription("Number of errors handled by the Redis client"),
			metric.WithUnit("{error}"),
		)
		if err != nil {
			return nil, fmt.Errorf("failed to create client errors metric: %w", err)
		}

		maintenanceNotifications, err = meter.Int64Counter(
			MetricMaintenanceNotifications,

View on GitHub (pinned to 36d97525cd)

Solutions

1. Search for other registrations of 'redis.client.connection.handoff' and ensure they use Int64Counter with matching description
2. Resolve transitive dependency conflicts between redisotel versions
3. Verify the MeterProvider is valid

Example fix

// before - conflicting type from another integration
meter.Int64UpDownCounter("redis.client.connection.handoff")

// after - match redisotel's Int64Counter type
meter.Int64Counter("redis.client.connection.handoff")

if err := obs.Init(cfg); err != nil {
    if strings.Contains(err.Error(), "connection handoff metric") {
        log.Error("conflict on 'redis.client.connection.handoff'; ensure Int64Counter type match")
    }
}

When it happens

Trigger: Calling Init with MetricGroupFlagConnectionBasic enabled, and the OTel SDK rejects the Counter creation.

Common situations: Another library or redisotel version registered 'redis.client.connection.handoff' with a conflicting instrument type (e.g., UpDownCounter) or different description; SDK incompatibility.

Related errors

• failed to create connection closed metric: %w
• failed to create connection count metric: %w
• failed to create connection create time histogram: %w
• failed to create connection relaxed timeout metric: %w
• failed to create client errors metric: %w

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