arduino/Arduino · critical · SSLError

Can't connect to HTTPS URL because the SSL module is not ava

Error message

Can't connect to HTTPS URL because the SSL module is not available.

What it means

urllib3 raises this SSLError in HTTPSConnectionPool._new_conn when the Python runtime has no usable `ssl` module. The code checks `if not ssl:` and, because the stdlib SSL-backed HTTPSConnection is also unavailable, it cannot build any HTTPS connection and aborts. This is an environment/build problem, not a network problem: the interpreter was compiled without SSL support (or OpenSSL bindings failed to load).

Source

Thrown at arduino-core/src/processing/app/i18n/python/requests/packages/urllib3/connectionpool.py:537

                                    strict, timeout, maxsize,
                                    block, headers)
        self.key_file = key_file
        self.cert_file = cert_file
        self.cert_reqs = cert_reqs
        self.ca_certs = ca_certs
        self.ssl_version = ssl_version

    def _new_conn(self):
        """
        Return a fresh :class:`httplib.HTTPSConnection`.
        """
        self.num_connections += 1
        log.info("Starting new HTTPS connection (%d): %s"
                 % (self.num_connections, self.host))

        if not ssl: # Platform-specific: Python compiled without +ssl
            if not HTTPSConnection or HTTPSConnection is object:
                raise SSLError("Can't connect to HTTPS URL because the SSL "
                               "module is not available.")

            return HTTPSConnection(host=self.host,
                                   port=self.port,
                                   strict=self.strict)

        connection = VerifiedHTTPSConnection(host=self.host,
                                             port=self.port,
                                             strict=self.strict)
        connection.set_cert(key_file=self.key_file, cert_file=self.cert_file,
                            cert_reqs=self.cert_reqs, ca_certs=self.ca_certs)

        connection.ssl_version = self.ssl_version

        return connection


def connection_from_url(url, **kw):

View on GitHub (pinned to a0df6e0e83)

Solutions

Verify the diagnosis: run `python -c "import ssl; print(ssl.OPENSSL_VERSION)"`; an ImportError/AttributeError confirms the missing module.
Rebuild/ reinstall Python with SSL support: install openssl headers (`sudo apt-get install libssl-dev`) then reinstall Python (pyenv: `pyenv install 3.x.x` after installing libssl-dev, or use the system/deadsnakes python).
As an interim workaround, fetch over plain HTTP if the endpoint allows it, or use an external tool (curl/wget) outside Python.
If a virtualenv/conda points at a broken interpreter, recreate it against a Python distribution that ships SSL support.

Example fix

// before (shell, failing build without SSL headers)
$ pyenv install 3.9.1   # -> _ssl module unavailable
// after (shell)
$ sudo apt-get install libssl-dev && pyenv install 3.9.1 && pyenv global 3.9.1
$ python -c "import ssl; print(ssl.OPENSSL_VERSION)"

Defensive patterns

Strategy: fallback

Validate before calling

def ssl_available():
    try:
        import ssl
        return hasattr(ssl, 'OPENSSL_VERSION')
    except Exception:
        return False

if not ssl_available():
    raise SystemExit('Python lacks SSL support; rebuild with OpenSSL headers before using HTTPS')

Type guard

def has_ssl() -> bool:
    try:
        import ssl  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

from requests.packages.urllib3.exceptions import SSLError
try:
    resp = session.get('https://example.com')
except SSLError as e:
    if 'SSL module is not available' in str(e):
        log.critical('Rebuild Python with OpenSSL support')
    else:
        raise

Prevention

Install libssl-dev/openssl headers before compiling Python from source (pyenv, docker builds).
Add `import ssl; ssl.OPENSSL_VERSION` to environment smoke tests in CI.
Prefer official Python builds or distro packages that ship the _ssl module.
After OpenSSL upgrades, reinstall/rebuild Python to keep _ssl.so linked correctly.

When it happens

Trigger: Any call that opens an HTTPS URL through urllib3 (e.g. requests.get('https://...'), urllib3.connectionpool.HTTPSConnectionPool.request) when `import ssl` fails because Python was compiled without the _ssl module, typically a from-source build without OpenSSL headers.

Common situations: Python built with pyenv/compile on Ubuntu/Debian missing libssl-dev; a hand-built interpreter without openssl headers; stripped-down Python distributions or embedded builds without the _ssl module; broken OpenSSL upgrade leaving _ssl.so unloadable.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

AI-assisted analysis of arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/176e31c2c47756ab. Report an issue: GitHub.