{"record":{"id":"9284debb0dac706d","repo":"python/cpython","slug":"stdlib-ssl-module-not-available","errorCode":null,"errorMessage":"stdlib ssl module not available","messagePattern":"stdlib ssl module not available","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"Lib/asyncio/sslproto.py","lineNumber":276,"sourceCode":"        # for test only\n        self._ssl_protocol._write_backlog.append(data)\n        self._ssl_protocol._write_buffer_size += len(data)\n\n\nclass SSLProtocol(protocols.BufferedProtocol):\n    max_size = 256 * 1024   # Buffer size passed to read()\n\n    _handshake_start_time = None\n    _handshake_timeout_handle = None\n    _shutdown_timeout_handle = None\n\n    def __init__(self, loop, app_protocol, sslcontext, waiter,\n                 server_side=False, server_hostname=None,\n                 call_connection_made=True,\n                 ssl_handshake_timeout=None,\n                 ssl_shutdown_timeout=None):\n        if ssl is None:\n            raise RuntimeError(\"stdlib ssl module not available\")\n\n        self._ssl_buffer = bytearray(self.max_size)\n        self._ssl_buffer_view = memoryview(self._ssl_buffer)\n\n        if ssl_handshake_timeout is None:\n            ssl_handshake_timeout = constants.SSL_HANDSHAKE_TIMEOUT\n        elif ssl_handshake_timeout <= 0:\n            raise ValueError(\n                f\"ssl_handshake_timeout should be a positive number, \"\n                f\"got {ssl_handshake_timeout}\")\n        if ssl_shutdown_timeout is None:\n            ssl_shutdown_timeout = constants.SSL_SHUTDOWN_TIMEOUT\n        elif ssl_shutdown_timeout <= 0:\n            raise ValueError(\n                f\"ssl_shutdown_timeout should be a positive number, \"\n                f\"got {ssl_shutdown_timeout}\")\n\n        if not sslcontext:","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/sslproto.py#L258-L294","documentation":"Raised in _SSLProtocol.__init__ as RuntimeError when the interpreter's ssl module is None, i.e. this Python build was compiled or installed without working OpenSSL bindings (the stdlib 'import ssl' failed and asyncio.sslproto.ssl is None). It fires as soon as any TLS-over-asyncio connection is attempted on such an interpreter.","triggerScenarios":"Any asyncio SSL usage — loop.create_connection(..., ssl=ctx), open_connection(ssl=True), create_server(ssl=ctx) — on a Python built without libssl headers or with an incompatible OpenSSL, or in minimal stripped-down runtime images.","commonSituations":"Custom-compiled CPython on a machine lacking libssl-dev; minimal Docker base images that strip the _ssl extension; macOS/Windows installers with broken SSL paths; exotic platforms (some embedded/AIX) shipping no OpenSSL; Conda/system Python mixes where the _ssl shared object cannot load its OpenSSL.","solutions":["Diagnose the root cause first: run `python -c \"import ssl\"` — its ImportError shows which shared library or version is missing.","Install OpenSSL development packages (e.g. apt install libssl-dev) and rebuild/reinstall Python so the _ssl extension is compiled.","Switch to an official Python distribution/docker image known to bundle working SSL (python:* official images, pyenv-built against system libssl).","For runtime library issues, fix loader paths (LD_LIBRARY_PATH / conda lib dirs) so _ssl can find libssl."],"exampleFix":"# before: python built without ssl -> RuntimeError on first TLS connection\nreader, writer = await asyncio.open_connection('host', 443, ssl=True)\n\n# after: verify at startup and fail fast with a clear message\nimport ssl\nif ssl is None:\n    raise SystemExit(\"this application requires a Python build with SSL support\")\nreader, writer = await asyncio.open_connection('host', 443, ssl=True)","handlingStrategy":"validation","validationCode":"# startup check, fails fast with a clear message\nimport sys\ntry:\n    import ssl\nexcept ImportError as e:\n    sys.exit(f'Python lacks SSL support ({e}); use a build with OpenSSL')\n\nssl_ctx = ssl.create_default_context()\nreader, writer = await asyncio.open_connection('host', 443, ssl=ssl_ctx)","typeGuard":"def ssl_available() -> bool:\n    try:\n        import ssl  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    conn = await loop.create_connection(proto, host, 443, ssl=ctx)\nexcept RuntimeError as e:\n    if 'stdlib ssl module not available' in str(e):\n        raise SystemExit('reinstall Python with OpenSSL support (libssl-dev + rebuild)')\n    raise","preventionTips":["Add `import ssl` to application startup so a broken build fails immediately, not at first TLS call.","Use official python docker images or distro packages that bundle _ssl.","When building CPython from source, install libssl-dev/openssl-devel first."],"tags":["asyncio","ssl","environment","build-issue","runtime-error"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}