Latest Sphinx (7.3.7) corrupted install on mambaforge

[aneeshnaik]

Details

My docs are built using mambaforge. If I list sphinx as a dependency (without a version number), then mambaforge tries to install the latest version (7.3.7), which leads to a long chain of error messages like below, and the build fails.

CondaVerificationError: The package for sphinx located at /home/docs/.asdf/installs/python/mambaforge-22.9.0-3/pkgs/sphinx-7.3.7-py312h5eee18b_0
appears to be corrupted. The path 'bin/sphinx-apidoc'
specified in the package manifest cannot be found.

CondaVerificationError: The package for sphinx located at /home/docs/.asdf/installs/python/mambaforge-22.9.0-3/pkgs/sphinx-7.3.7-py312h5eee18b_0
appears to be corrupted. The path 'bin/sphinx-autogen'
specified in the package manifest cannot be found.

CondaVerificationError: The package for sphinx located at /home/docs/.asdf/installs/python/mambaforge-22.9.0-3/pkgs/sphinx-7.3.7-py312h5eee18b_0
appears to be corrupted. The path 'bin/sphinx-build'
specified in the package manifest cannot be found.

CondaVerificationError: The package for sphinx located at /home/docs/.asdf/installs/python/mambaforge-22.9.0-3/pkgs/sphinx-7.3.7-py312h5eee18b_0
appears to be corrupted. The path 'bin/sphinx-quickstart'
specified in the package manifest cannot be found.

However, if I list sphinx=7.2 then the build works as expected.

Here is my .readthedocs.yaml file:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "mambaforge-22.9"

sphinx:
  configuration: docs/source/conf.py

conda:
  environment: docs/environment.yml

And here is the version of the environment.yml file that does not work:

channels:
  - defaults
  - conda-forge
dependencies:
  - sphinx
  - sphinx-book-theme
  - numpy
  - numpydoc
  - myst-nb=1.0.0
  - lintsampler
  - matplotlib
  - scipy
  - scikit-learn

Here is an example of a failed build using this environment.yml file.

[humitos]

Hi. Can you reproduce this issue locally?

[aneeshnaik]

No, the docs build if I try locally with the same conda environment.

[victorlin]

Solution:

-     python: "mambaforge-22.9"
+     python: "mambaforge-23.11"

---

I did some searching on the root error message which wasn't included in the issue description but you can see it in the build log that's linked:

critical libmamba Pathname can't be converted from UTF-8 to current locale.
Preparing transaction: ...working... done
Verifying transaction: ...working... failed

and came across https://github.com/conda-forge/python-libarchive-c-feedstock/issues/35#issuecomment-1623133587. This is a known bug in mamba versions <1.4.7. The mambaforge version used here, 22.9, bundles mamba 1.1.0. The next available mambaforge version, 23.11, bundles mamba 1.5.5.

[humitos]

@victorlin thanks for posting the solution here! 🙏🏼

@aneeshnaik can you try using mambaforge-23.11 and let us know if it solves the issue?

[aneeshnaik]

Just tested building the docs with mambaforge-23.11 and everything builds without error, even if I remove the sphinx version spec so that it uses the latest sphinx version (7.3.7).

In summary, @victorlin's solution works --- thank you for looking into this!

[humitos]

Great! Thanks for replying here. I'm going to close this issue then, since it's not an issue on Read the Docs and there isn't anything actionable from our side.