{"id":"9a755d5ab412d55e","repo":"redis/redis-py","slug":"max-connections-must-be-a-positive-integer-9a755d","errorCode":null,"errorMessage":"\"max_connections\" must be a positive integer","messagePattern":"\"max_connections\" must be a positive integer","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"redis/connection.py","lineNumber":2978,"sourceCode":"        url_options = parse_url(url)\n\n        if \"connection_class\" in kwargs:\n            url_options[\"connection_class\"] = kwargs[\"connection_class\"]\n\n        kwargs.update(url_options)\n        return cls(**kwargs)\n\n    def __init__(\n        self,\n        connection_class=Connection,\n        max_connections: Optional[int] = None,\n        cache_factory: Optional[CacheFactoryInterface] = None,\n        maint_notifications_config: Optional[MaintNotificationsConfig] = None,\n        **connection_kwargs,\n    ):\n        max_connections = max_connections or 100\n        if not isinstance(max_connections, int) or max_connections < 0:\n            raise ValueError('\"max_connections\" must be a positive integer')\n\n        self.connection_class = connection_class\n        self._connection_kwargs = connection_kwargs\n        self.max_connections = max_connections\n        self.cache = None\n        self._cache_factory = cache_factory\n\n        try:\n            supports_maint_notifications = issubclass(\n                connection_class, MaintNotificationsAbstractConnection\n            )\n            is_unix_domain_socket_connection = issubclass(\n                connection_class, UnixDomainSocketConnection\n            )\n        except TypeError:\n            supports_maint_notifications = False\n            is_unix_domain_socket_connection = False\n","sourceCodeStart":2960,"sourceCodeEnd":2996,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/connection.py#L2960-L2996","documentation":"Raised as a ValueError by ConnectionPool.__init__ (connection.py:2976-2978) when max_connections is not an int or is negative. Note line 2976 first applies `max_connections = max_connections or 100`, so falsy values (None, 0) are replaced by 100 and pass; only truthy non-int values (e.g. 5.5, \"10\") or negative ints actually raise.","triggerScenarios":"Passing max_connections as a float (50.0 is still an int check failure? no — 50.0 is a float, isinstance(50.0, int) is False, so it raises), a string (\"50\"), or a negative integer (-1) to ConnectionPool / BlockingConnectionPool / Redis(max_connections=...). Also via from_url query (?max_connections=-5).","commonSituations":"Config loaders returning typed values from YAML/JSON that deserialize numbers as floats; env-var parsing that leaves the value as a string; accidentally computing max_connections from an expression that yields a float; passing a negative to mean 'unlimited'.","solutions":["Pass a positive int (or None to use the default of 100): max_connections=50.","If the value comes from config/env, coerce explicitly: max_connections=int(value) after validating it is >= 0.","Do not use a negative number to mean unlimited — there is no unlimited sentinel; choose a large positive int instead."],"exampleFix":"# before\npool = redis.ConnectionPool(max_connections=\"50\")\n# or\npool = redis.ConnectionPool(max_connections=50.0)\n\n# after\npool = redis.ConnectionPool(max_connections=int(50))\n# or rely on default\npool = redis.ConnectionPool()  # max_connections=100","handlingStrategy":"validation","validationCode":"def coerce_max_connections(v):\n    if v is None:\n        return 100\n    v = int(v)\n    if v < 0:\n        raise ValueError(\"max_connections must be >= 0\")\n    return v\n\npool = redis.ConnectionPool(max_connections=coerce_max_connections(raw))","typeGuard":"def is_valid_max_connections(v) -> bool:\n    return isinstance(v, int) and v >= 0","tryCatchPattern":"try:\n    pool = redis.ConnectionPool(max_connections=raw)\nexcept ValueError as e:\n    if \"max_connections\" in str(e):\n        pool = redis.ConnectionPool(max_connections=int(raw))\n    else:\n        raise","preventionTips":["Coerce config/env values to int before passing max_connections.","Validate numeric config in your config loader.","Treat negative values as invalid, not as 'unlimited'."],"tags":["connection-pool","configuration","validation"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}