{"record":{"id":"c3ff5d2bf2d93df7","repo":"python/cpython","slug":"python-ssl-module-is-not-available","errorCode":null,"errorMessage":"Python ssl module is not available","messagePattern":"Python ssl module is not available","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"Lib/asyncio/base_events.py","lineNumber":1340,"sourceCode":"                await proto.drain()\n                total_sent += read\n        finally:\n            if total_sent > 0 and hasattr(file, 'seek'):\n                file.seek(offset + total_sent)\n            await proto.restore()\n\n    async def start_tls(self, transport, protocol, sslcontext, *,\n                        server_side=False,\n                        server_hostname=None,\n                        ssl_handshake_timeout=None,\n                        ssl_shutdown_timeout=None):\n        \"\"\"Upgrade transport to TLS.\n\n        Return a new transport that *protocol* should start using\n        immediately.\n        \"\"\"\n        if ssl is None:\n            raise RuntimeError('Python ssl module is not available')\n\n        if not isinstance(sslcontext, ssl.SSLContext):\n            raise TypeError(\n                f'sslcontext is expected to be an instance of ssl.SSLContext, '\n                f'got {sslcontext!r}')\n\n        if not getattr(transport, '_start_tls_compatible', False):\n            raise TypeError(\n                f'transport {transport!r} is not supported by start_tls()')\n\n        waiter = self.create_future()\n        ssl_protocol = sslproto.SSLProtocol(\n            self, protocol, sslcontext, waiter,\n            server_side, server_hostname,\n            ssl_handshake_timeout=ssl_handshake_timeout,\n            ssl_shutdown_timeout=ssl_shutdown_timeout,\n            call_connection_made=False)\n","sourceCodeStart":1322,"sourceCodeEnd":1358,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/base_events.py#L1322-L1358","documentation":"A RuntimeError raised by loop.start_tls() when the interpreter was built without a working ssl module (asyncio's optional ssl import is None). start_tls exists purely to negotiate TLS, so with no ssl module it cannot proceed and reports unavailability rather than crashing deeper in the stack.","triggerScenarios":"Calling await loop.start_tls(transport, protocol, ctx) on a Python built with the ssl extension disabled (misconfigured build, --without-ssl, or a platform where OpenSSL dev headers were missing at build time).","commonSituations":"Minimal/stripped Python builds in tiny containers or embedded distributions; distro Pythons compiled without OpenSSL linkage; CI images that trimmed development libraries before building Python.","solutions":["Reinstall or rebuild Python against OpenSSL (e.g. apt install libssl-dev before pyenv install).","Use a distribution/binary that ships the ssl module; verify with python -c \"import ssl\".","Gate TLS code paths on ssl availability so non-TLS operation still works."],"exampleFix":"# before\ntransport = await loop.start_tls(raw_tp, proto, ctx)  # RuntimeError\n\n# after\nimport sys\nif 'ssl' not in sys.modules or sys.modules.get('ssl') is None:\n    raise RuntimeError('TLS unavailable: this Python lacks the ssl module')\ntransport = await loop.start_tls(raw_tp, proto, ctx)","handlingStrategy":"validation","validationCode":"try:\n    import ssl\nexcept ImportError:\n    raise RuntimeError('TLS unavailable: Python built without the ssl module')","typeGuard":null,"tryCatchPattern":"try:\n    tp = await loop.start_tls(raw_tp, proto, ctx)\nexcept RuntimeError as e:\n    if 'ssl module is not available' not in str(e):\n        raise\n    raise RuntimeError('rebuild Python with OpenSSL support') from e","preventionTips":["Run python -c 'import ssl' as an environment sanity check in Dockerfiles and CI.","Install libssl-dev (or platform equivalent) before building Python from source.","Gate TLS features behind ssl availability so startup fails with a clear message."],"tags":["asyncio","tls","ssl","environment","build"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}