SSL handshake failures calling HubSpot API from Python on macOS

TL;DR

Run the Install Certificates command file that ships in your Python install directory (usually under /Applications/Python 3.x/), with sudo if needed, to install the certifi root bundle. Environment fix, per commenter lborruto.

Steps

1. Environment fix, per commenter lborruto. Some macOS Python installations (notably python.org builds) ship without a set of default root certificates, so TLS to api.hubapi.com fails the handshake. Run the Install Certificates command file that ships in your Python install directory (usually under /Applications/Python 3.x/), with sudo if needed, to install the certifi root bundle. After that the same ETL code connects cleanly. If only your Mac fails while Linux CI passes, check the local cert store before anything else.

When to use

You are seeing this: Issue HubSpot/hubspot-api-python#221 (closed, 5 comments): Random SSL handshake failures when calling api.hubapi.com from the HubSpot Python client on macOS: HTTPSConnectionPool Max retries exceeded. Use this skill when you run into "SSL handshake failures calling HubSpot API from Python on macOS".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The same code works on other machines, so it looks like a HubSpot-side TLS problem but is not.

In gh:HubSpot/hubspot-api-python#221 (HubSpot), the issue reported was: Issue HubSpot/hubspot-api-python#221 (closed, 5 comments): Random SSL handshake failures when calling api.hubapi.com from the HubSpot Python client on macOS: HTTPSConnectionPool Max retries exceeded. The same code works on other machines, so it looks like a HubSpot-side TLS problem but is not. The verified resolution from the thread: Environment fix, per commenter lborruto. Some macOS Python installations (notably python.org builds) ship without a set of default root certificates, so TLS to api.hubapi.com fails the handshake. Run the Install Certificates command file that ships in your Python install directory (usually under /Applications/Python 3.x/), with sudo if needed, to install the certifi root bundle. After that the same ETL code connects cleanly. If only your Mac fails while Linux CI passes, check the local cert store before anything else. Source: mount the host path https at container path //github.com/HubSpot/hubspot-api-python/issues/221