{"record":{"id":"92a6113ea023e31c","repo":"aio-libs/aiohttp","slug":"timeout-parameter-cannot-be-of-type-timeout-typ","errorCode":null,"errorMessage":"timeout parameter cannot be of {type(timeout)} type, please use 'timeout=ClientTimeout(...)'","messagePattern":"timeout parameter cannot be of (.+?) type, please use 'timeout=ClientTimeout\\(\\.\\.\\.\\)'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"aiohttp/client.py","lineNumber":350,"sourceCode":"        else:\n            self._base_url = URL(base_url)\n            self._base_url_origin = self._base_url.origin()\n            assert self._base_url.absolute, \"Only absolute URLs are supported\"\n        if self._base_url is not None and not self._base_url.path.endswith(\"/\"):\n            raise ValueError(\"base_url must have a trailing '/'\")\n\n        if not isinstance(ssl, SSL_ALLOWED_TYPES):\n            raise TypeError(\n                \"ssl should be SSLContext, Fingerprint, or bool, \"\n                f\"got {ssl!r} instead.\"\n            )\n\n        loop = asyncio.get_running_loop()\n\n        if timeout is sentinel or timeout is None:\n            timeout = ClientTimeout()\n        if not isinstance(timeout, ClientTimeout):\n            raise ValueError(\n                f\"timeout parameter cannot be of {type(timeout)} type, \"\n                \"please use 'timeout=ClientTimeout(...)'\",\n            )\n        self._timeout = timeout\n\n        if ssl_shutdown_timeout is not sentinel:\n            warnings.warn(\n                \"The ssl_shutdown_timeout parameter is deprecated and will be removed in aiohttp 4.0\",\n                DeprecationWarning,\n                stacklevel=2,\n            )\n\n        if connector is None:\n            connector = TCPConnector(ssl_shutdown_timeout=ssl_shutdown_timeout)\n        # Initialize these three attrs before raising any exception,\n        # they are used in __del__\n        self._connector = connector\n        self._loop = loop","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/client.py#L332-L368","documentation":"Raised by ClientSession.__init__ when timeout is neither None, the sentinel, nor a ClientTimeout instance. aiohttp models multiple timeouts (total, connect, sock_connect, sock_read) as a single structured object; a bare number has no unambiguous mapping.","triggerScenarios":"Calling ClientSession(timeout=30), ClientSession(timeout=10.0), or passing a (connect, read) tuple. Anything that is not a ClientTimeout trips the isinstance check.","commonSituations":"Coming from requests/httpx where timeout=30 (seconds) is the documented form. Reading a numeric timeout from config and passing it directly. Treating timeout as a float out of habit from asyncio.wait_for.","solutions":["Wrap the value: ClientSession(timeout=ClientTimeout(total=30)).","For granular control: ClientTimeout(connect=5, sock_read=30).","If the value comes from config as a number, convert at the boundary: ClientTimeout(total=cfg['timeout'])."],"exampleFix":"// before\nsession = ClientSession(timeout=30)\n// after\nfrom aiohttp import ClientTimeout\nsession = ClientSession(timeout=ClientTimeout(total=30))","handlingStrategy":"validation","validationCode":"from aiohttp import ClientSession, ClientTimeout\n\ndef make_session(timeout_value):\n    if isinstance(timeout_value, (int, float)):\n        timeout_value = ClientTimeout(total=timeout_value)\n    return ClientSession(timeout=timeout_value)","typeGuard":"from aiohttp import ClientTimeout\n\ndef is_client_timeout(v) -> bool:\n    return isinstance(v, ClientTimeout)","tryCatchPattern":"try:\n    session = ClientSession(timeout=t)\nexcept ValueError as e:\n    if 'timeout parameter cannot be' in str(e) and isinstance(t, (int, float)):\n        session = ClientSession(timeout=ClientTimeout(total=t))\n    else:\n        raise","preventionTips":["Never pass a bare number as timeout; always wrap in ClientTimeout.","Keep a single helper that converts config values to ClientTimeout.","Annotate public APIs with ClientTimeout, not float."],"tags":["timeout","client-session","type-validation"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}