Could not import extension sphinx.builders.linkcheck (exception: urllib3 v2.0 only supports OpenSSL 1.1.1+)

[stereoshoots]

Details

• Read the Docs project URL: https://readthedocs.org/projects/gitlab-board
• Build URL (if applicable): https://readthedocs.org/projects/gitlab-board/builds/20387388/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/stereoshoots/

Expected Result

New revision of docs should be builded.

Actual Result

Error is thrown:

Could not import extension sphinx.builders.linkcheck (exception: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with OpenSSL 1.0.2n  7 Dec 2017. See: https://github.com/urllib3/urllib3/issues/2168)

Is this a problem on my side? It installs pip packages in build, how should i fix this?

[stsewd]

Hi, this is because urlib3 was released yesterday, and that version isn't compatible with the docker image you are using. To use a more recent version of our docker images, please use a config file (https://docs.readthedocs.io/en/stable/config-file/v2.html), or pin urllib3 in your requirements to a previous version.

Edit: projects should use a configuration file and leave urllib3 unpinned

[agjohnson]

More specifically, you should use a configuration file that that specifies the build OS.

That is, add a .readthedocs.yaml file in your repository root:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

This will ensure you are not using one of the older images.

Edit: updated to mention build.tools

[sethmlarson]

@stsewd I suspect this issue will get a lot of traffic, if possible could the correct answer w/ example of upgrading to build.os: ubuntu-22.04 instead of pinning urllib3 be elevated to the first reply. I suspect folks may be looking for quick solutions to this incompatibility and I'd like people to keep urllib3 unpinned if it's not blocked by anything else in their environment.

[agjohnson]

@sethmlarson Thanks for the note, I'd agree the configuration fix should be the recommended fix. I'll edit the guidance above.

It seems like we're probably going to aim to get some sort of fix out here, as this is causing a bit of trouble for folks. It seems the trouble is an old pyenv compiled Python in an image we're trying to deprecate, but should be something we can fix.

Unfortunately, we're going into Write the Docs conference time, so we haven't settled on a timeframe yet.

[agjohnson]

Also, I opened an issue yesterday for updating and fixing the legacy build image:
readthedocs/readthedocs-docker-images#194

We'll track updating and fixing the image there. I'll see what I can do today and tomorrow