go-redis/redis · warning

invalid notification format

Error message

invalid notification format

What it means

Returned by the push notification handler (push_notification_handler.go:26,32,82,...) when an incoming maintenance push notification is malformed — e.g. empty notification array, non-string notification type, wrong field types/counts in a MOVING/MIGRATING frame. It indicates the RESP3 push payload did not match the expected schema for that notification type.

Source

Thrown at maintnotifications/errors.go:41

	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
	ErrConnectionMarkedForHandoff = errors.New(logs.ConnectionMarkedForHandoffErrorMessage)
	// ErrConnectionMarkedForHandoffWithState is returned when a connection is marked for handoff
	// and should not be used until the handoff is complete
	ErrConnectionMarkedForHandoffWithState = errors.New(logs.ConnectionMarkedForHandoffErrorMessage + " with state")
	// ErrConnectionInvalidHandoffState is returned when a connection is in an invalid state for handoff
	ErrConnectionInvalidHandoffState = errors.New(logs.ConnectionInvalidHandoffStateErrorMessage)
)

// shutdown errors
var (
	// ErrShutdown is returned when the maintnotifications manager is shutdown
	ErrShutdown = errors.New(logs.ShutdownError())

View on GitHub (pinned to 36d97525cd)

Solutions

1. Check server and client versions match on the MOVING/MIGRATING/SMIGRATING schema (see AGENTS.md maintnotifications spec).
2. Inspect the logged payload (logged at the InvalidNotification* call sites) to see which field is wrong.
3. If a proxy is in the path, verify it forwards RESP3 push frames unmodified.
4. Upgrade go-redis / Redis to compatible versions; this is almost always a version or protocol-translation mismatch, not a client bug.

if errors.Is(err, maintnotifications.ErrInvalidNotification) {
    // server sent a malformed maintenance push frame. 
    // Check version compatibility / proxy passthrough; not actionable per-command.
    log.Debug("ignoring malformed maint notification: %v", err)
}

When it happens

Trigger: A RESP3 push frame arrives whose contents fail schema validation: MOVING with <3 fields, a non-int64 seqID/timeS, a non-string endpoint, or a nil handler-context connection. Each guard in the handler returns ErrInvalidNotification and logs the offending payload via logs.InvalidNotification*.

Common situations: Server/client version skew where the server emits a notification shape the client doesn't expect; a proxy or RESP-interceptor mangling push frames; a Redis fork emitting non-standard maintenance notifications; testing with hand-crafted push payloads that omit required fields.

Related errors

• invalid client type
• max handoff retries reached
• handoff queue is full, cannot queue new handoff requests - c
• connection is in invalid state for handoff
• shutdown

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