{"id":"7760be2a6ed7e69b","repo":"go-redis/redis","slug":"handoff-queue-size-must-be-greater-than-0","errorCode":null,"errorMessage":"handoff queue size must be greater than 0","messagePattern":"handoff queue size must be greater than 0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"maintnotifications/errors.go","lineNumber":13,"sourceCode":"package maintnotifications\n\nimport (\n\t\"errors\"\n\n\t\"github.com/redis/go-redis/v9/internal/maintnotifications/logs\"\n)\n\n// Configuration errors\nvar (\n\tErrInvalidRelaxedTimeout             = errors.New(logs.InvalidRelaxedTimeoutError())\n\tErrInvalidHandoffTimeout             = errors.New(logs.InvalidHandoffTimeoutError())\n\tErrInvalidHandoffWorkers             = errors.New(logs.InvalidHandoffWorkersError())\n\tErrInvalidHandoffQueueSize           = errors.New(logs.InvalidHandoffQueueSizeError())\n\tErrInvalidPostHandoffRelaxedDuration = errors.New(logs.InvalidPostHandoffRelaxedDurationError())\n\tErrInvalidEndpointType               = errors.New(logs.InvalidEndpointTypeError())\n\tErrInvalidMaintNotifications         = errors.New(logs.InvalidMaintNotificationsError())\n\tErrMaxHandoffRetriesReached          = errors.New(logs.MaxHandoffRetriesReachedError())\n\n\t// Configuration validation errors\n\n\t// ErrInvalidHandoffRetries is returned when the number of handoff retries is invalid\n\tErrInvalidHandoffRetries = errors.New(logs.InvalidHandoffRetriesError())\n)\n\n// Integration errors\nvar (\n\t// ErrInvalidClient is returned when the client does not support push notifications\n\tErrInvalidClient = errors.New(logs.InvalidClientError())\n)\n","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/go-redis/redis/blob/36d97525cd8076aed67cddf54778e9ea84550929/maintnotifications/errors.go#L1-L31","documentation":"Returned by Config.Validate() (maintnotifications/config.go:170-172) when Config.HandoffQueueSize is negative. HandoffQueueSize sizes the buffered channel that queues pending connection handoffs (handoff_worker.go:49). The message says 'must be greater than 0' but the actual check is < 0, so 0 is permitted (it triggers auto-calculation); only negatives fail.","triggerScenarios":"Setting Options.MaintNotificationsConfig.HandoffQueueSize to a negative number, then constructing the client (which calls Validate()). For example passing a value parsed from an env var or computed as poolSize - someConstant that can go negative for small pools.","commonSituations":"Operator sets a queue size from a config flag that defaults to -1; a formula like `desired - overhead` underflows for tiny pools; assuming the field required a positive integer when 0 is the 'auto' sentinel.","solutions":["Set HandoffQueueSize to 0 to let the library scale it (max(20*workers, poolSize), capped by MaxActiveConns+1 or 5*poolSize).","Set an explicit positive value (minimum 200 is enforced when you set it yourself, per config.go:265).","Audit any env/config parsing that can produce negative integers for this field."],"exampleFix":"// before\ncfg := &maintnotifications.Config{HandoffQueueSize: -5}\n\n// after\ncfg := &maintnotifications.Config{HandoffQueueSize: 0} // auto-scale","handlingStrategy":"validation","validationCode":"if cfg.HandoffQueueSize < 0 {\n    cfg.HandoffQueueSize = 0 // auto-scale from pool size\n}\nif err := cfg.Validate(); err != nil {\n    return fmt.Errorf(\"maint config: %w\", err)\n}","typeGuard":"func validQueueSize(n int) bool { return n >= 0 }","tryCatchPattern":null,"preventionTips":["Use 0 for auto-scaling; an explicit value is floored to 200.","Document the auto-scale formula next to the config field in your own config schema.","Validate config in tests, not only at runtime."],"tags":["maintnotifications","config","validation","handoff"],"analyzedSha":"36d97525cd8076aed67cddf54778e9ea84550929","analyzedAt":"2026-08-06T01:08:27.376Z","schemaVersion":2}