go-redis/redis · error

invalid client type

Error message

invalid client type

What it means

Returned by NewManager (manager.go:128) when the supplied client is nil, and by setupPushNotifications (manager.go:230) when the client has no push-notification processor. Maintenance notifications require a client that implements ClientInterface and exposes a RESP3 push processor (Protocol: 3) to receive MOVING/MIGRATING frames.

Source

Thrown at maintnotifications/errors.go:29

	ErrInvalidRelaxedTimeout             = errors.New(logs.InvalidRelaxedTimeoutError())
	ErrInvalidHandoffTimeout             = errors.New(logs.InvalidHandoffTimeoutError())
	ErrInvalidHandoffWorkers             = errors.New(logs.InvalidHandoffWorkersError())
	ErrInvalidHandoffQueueSize           = errors.New(logs.InvalidHandoffQueueSizeError())
	ErrInvalidPostHandoffRelaxedDuration = errors.New(logs.InvalidPostHandoffRelaxedDurationError())
	ErrInvalidEndpointType               = errors.New(logs.InvalidEndpointTypeError())
	ErrInvalidMaintNotifications         = errors.New(logs.InvalidMaintNotificationsError())
	ErrMaxHandoffRetriesReached          = errors.New(logs.MaxHandoffRetriesReachedError())

	// Configuration validation errors

	// ErrInvalidHandoffRetries is returned when the number of handoff retries is invalid
	ErrInvalidHandoffRetries = errors.New(logs.InvalidHandoffRetriesError())
)

// Integration errors
var (
	// ErrInvalidClient is returned when the client does not support push notifications
	ErrInvalidClient = errors.New(logs.InvalidClientError())
)

// Handoff errors
var (
	// ErrHandoffQueueFull is returned when the handoff queue is full
	ErrHandoffQueueFull = errors.New(logs.HandoffQueueFullError())
)

// Notification errors
var (
	// ErrInvalidNotification is returned when a notification is in an invalid format
	ErrInvalidNotification = errors.New(logs.InvalidNotificationError())
)

// connection handoff errors
var (
	// ErrConnectionMarkedForHandoff is returned when a connection is marked for handoff
	// and should not be used until the handoff is complete

View on GitHub (pinned to 36d97525cd)

Solutions

1. Ensure Options.Protocol = 3 is set so the client negotiates RESP3 and builds a push processor.
2. Use the standard redis.Client / ClusterClient which implement ClientInterface with push support; do not pass nil.
3. If wrapping the client, ensure your wrapper delegates GetPushProcessor() to the underlying real client.

Example fix

// before
opt := &redis.Options{Addr: addr, MaintNotificationsConfig: maintnotifications.DefaultConfig()}
// Protocol omitted -> push processor absent -> ErrInvalidClient

// after
opt := &redis.Options{
  Addr: addr,
  Protocol: 3, // RESP3 required for push notifications
  MaintNotificationsConfig: maintnotifications.DefaultConfig(),
}

opt.Protocol = 3 // RESP3 required for push notifications
if err := maintCfg.Validate(); err != nil {
    return err
}

_, err := maintnotifications.NewManager(client, pool, cfg)
if errors.Is(err, maintnotifications.ErrInvalidClient) {
    // client is nil or lacks a push processor; ensure Protocol=3 and a real client type
}

When it happens

Trigger: Passing nil to NewManager; or enabling maintnotifications on a client type that does not support push notifications (e.g. a minimal/mock client without GetPushProcessor). Also surfaces if RESP3 (Options.Protocol=3) is not negotiated, since the push processor may be absent.

Common situations: Enabling MaintNotificationsConfig on a custom UniversalClient wrapper that doesn't forward push support; forgetting to set Options.Protocol = 3 (required per AGENTS.md maintnotifications spec); a test stub client missing the processor.

Related errors

• invalid notification format
• failed to enable maintnotifications: server does not support
• MaxWorkers must be greater than or equal to 0
• handoff queue size must be greater than 0
• post-handoff relaxed duration must be greater than or equal

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