What causes "handler cannot be nil" in go-redis/redis?

Ensure the handler passed to Register is non-nil before calling it.

handler cannot be nil

Error message

handler cannot be nil

What it means

push.ErrHandlerNil is returned when a caller registers a nil handler with a push notification processor (the Registry). The push package dispatches RESP3 push notifications (e.g. maintenance MOVING/MIGRATING signals) to registered handlers; a nil handler would panic on dispatch, so registration is rejected. It is a sentinel error checkable via push.IsHandlerNilError / errors.Is.

Source

Thrown at push/errors.go:48

	ProcessorTypeCustom        = ProcessorType("custom")
)

// ProcessorOperation represents the operation being performed by the processor
// defined as a custom type for better readability and easier maintenance
type ProcessorOperation string

const (
	// ProcessorOperations
	ProcessorOperationProcess    = ProcessorOperation("process")
	ProcessorOperationRegister   = ProcessorOperation("register")
	ProcessorOperationUnregister = ProcessorOperation("unregister")
	ProcessorOperationUnknown    = ProcessorOperation("unknown")
)

// Common error variables for reuse
var (
	// ErrHandlerNil is returned when attempting to register a nil handler
	ErrHandlerNil = errors.New(ReasonHandlerNil)
)

// Registry errors

// ErrHandlerExists creates an error for when attempting to overwrite an existing handler
func ErrHandlerExists(pushNotificationName string) error {
	return NewHandlerError(ProcessorOperationRegister, pushNotificationName, ReasonHandlerExists, nil)
}

// ErrProtectedHandler creates an error for when attempting to unregister a protected handler
func ErrProtectedHandler(pushNotificationName string) error {
	return NewHandlerError(ProcessorOperationUnregister, pushNotificationName, ReasonHandlerProtected, nil)
}

// VoidProcessor errors

// ErrVoidProcessorRegister creates an error for when attempting to register a handler on void processor
func ErrVoidProcessorRegister(pushNotificationName string) error {

View on GitHub (pinned to 36d97525cd)

Solutions

Ensure the handler passed to Register is non-nil before calling it.
Check the handler variable for nil with an explicit guard before registration.
If the handler is optional, skip registration entirely rather than passing nil.

Example fix

// before
registry.Register("MOVING", nil)

// after
if handler == nil {
    return errors.New("handler must not be nil")
}
registry.Register("MOVING", handler)

Defensive patterns

Strategy: validation

Validate before calling

func safeRegister(r *push.Registry, name string, h push.Handler) error {
    if h == nil {
        return push.ErrHandlerNil
    }
    return r.Register(name, h)
}

Type guard

func isNilHandler(h push.Handler) bool {
    return h == nil // Handler is an interface; a nil interface compares to nil
}

Try / catch

if err := registry.Register(name, handler); err != nil {
    if push.IsHandlerNilError(err) {
        // handler was nil; initialize it before retrying
    }
}

Prevention

Always nil-check handler variables before registering them.
If a handler is optional, skip registration rather than passing nil.
Initialize handlers at construction time to avoid nil from missed branches.

When it happens

Trigger: Calling Register on a push processor/registry with a nil handler function. Passing an uninitialized handler variable. Conditionally building a handler that ends up nil due to a missed branch.

Common situations: Custom RESP3 push-notification integrations. Maintenance-notifications subsystem extensions that register handlers programmatically. Test code that stubs out handlers with nil.

Related errors

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