lightgbm: build failing with "There was a problem with Read the Docs"

[jameslamb]

Details

• Read the Docs project URL: https://readthedocs.org/projects/lightgbm
• Build URL (if applicable): https://readthedocs.org/projects/lightgbm/builds/26941961/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/jameslamb

Expected Result

I pushed branch python-3.13 to https://github.com/microsoft/LightGBM (microsoft/LightGBM#6668).

Added that branch as a "version" at https://readthedocs.org/projects/lightgbm/versions/, then triggered a build of it:

I expected that either:

• the build would succeed
• the build would fail but with log output I could inspect for issues

Actual Result

Builds repeatedly failed (4 in a row over the last 24 hours), with a banner like the following:

Error

There was a problem with Read the Docs while building your documentation. Please try again later. If this problem persists, report this error to us with your build id (26941961).

I don't see any clues in the logs.

full raw log output (click me)

Read the Docs build information
Build id: 26941961
Project: lightgbm
Version: python-3.13
Commit: 811ee8de4d9bb6006d6b20edc66ae675ec9204a5
Date: 2025-01-23T04:04:07.756544Z
State: finished
Success: False


[rtd-command-info] start-time: 2025-01-23T04:04:08.295968Z, end-time: 2025-01-23T04:04:08.994830Z, duration: 0, exit-code: 0
git clone --depth 1 https://github.com/Microsoft/LightGBM .
Cloning into '.'...

[rtd-command-info] start-time: 2025-01-23T04:04:09.017959Z, end-time: 2025-01-23T04:04:09.490135Z, duration: 0, exit-code: 0
git fetch origin --force --prune --prune-tags --depth 50 refs/heads/python-3.13:refs/remotes/origin/python-3.13
From https://github.com/Microsoft/LightGBM
 * [new branch]      python-3.13 -> origin/python-3.13

[rtd-command-info] start-time: 2025-01-23T04:04:09.566110Z, end-time: 2025-01-23T04:04:09.726988Z, duration: 0, exit-code: 0
git checkout --force origin/python-3.13
Note: switching to 'origin/python-3.13'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 811ee8d Merge branch 'python-3.13' of github.com:microsoft/LightGBM into python-3.13

[rtd-command-info] start-time: 2025-01-23T04:04:09.750579Z, end-time: 2025-01-23T04:04:09.801169Z, duration: 0, exit-code: 0
cat .readthedocs.yaml
version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "miniconda3-4.7"
conda:
  environment: docs/env.yml
formats:
  - pdf
sphinx:
  builder: html
  configuration: docs/conf.py
  fail_on_warning: true
submodules:
  include: all
  recursive: true

[rtd-command-info] start-time: 2025-01-23T04:04:09.889746Z, end-time: 2025-01-23T04:04:09.965153Z, duration: 0, exit-code: 0
git submodule sync


[rtd-command-info] start-time: 2025-01-23T04:04:09.986370Z, end-time: 2025-01-23T04:04:22.990317Z, duration: 13, exit-code: 0
git submodule update --init --force --recursive --
Submodule 'include/boost/compute' (https://github.com/boostorg/compute) registered for path 'external_libs/compute'
Submodule 'eigen' (https://gitlab.com/libeigen/eigen.git) registered for path 'external_libs/eigen'
Submodule 'external_libs/fast_double_parser' (https://github.com/lemire/fast_double_parser.git) registered for path 'external_libs/fast_double_parser'
Submodule 'external_libs/fmt' (https://github.com/fmtlib/fmt.git) registered for path 'external_libs/fmt'
Cloning into '/home/docs/checkouts/readthedocs.org/user_builds/lightgbm/checkouts/python-3.13/external_libs/compute'...
Cloning into '/home/docs/checkouts/readthedocs.org/user_builds/lightgbm/checkouts/python-3.13/external_libs/eigen'...
Cloning into '/home/docs/checkouts/readthedocs.org/user_builds/lightgbm/checkouts/python-3.13/external_libs/fast_double_parser'...
Cloning into '/home/docs/checkouts/readthedocs.org/user_builds/lightgbm/checkouts/python-3.13/external_libs/fmt'...
Submodule path 'external_libs/compute': checked out '36350b7de849300bd3d72a05d8bf890ca405a014'
Submodule path 'external_libs/eigen': checked out '3147391d946bb4b6c68edd901f2add6ac1f31f8c'
Submodule path 'external_libs/fast_double_parser': checked out 'efec03532ef65984786e5e32dbc81f6e6a55a115'
Submodule 'benchmark/dependencies/abseil-cpp' (https://github.com/abseil/abseil-cpp.git) registered for path 'external_libs/fast_double_parser/benchmarks/dependencies/abseil-cpp'
Submodule 'benchmark/dependencies/double-conversion' (https://github.com/google/double-conversion.git) registered for path 'external_libs/fast_double_parser/benchmarks/dependencies/double-conversion'
Cloning into '/home/docs/checkouts/readthedocs.org/user_builds/lightgbm/checkouts/python-3.13/external_libs/fast_double_parser/benchmarks/dependencies/abseil-cpp'...
Cloning into '/home/docs/checkouts/readthedocs.org/user_builds/lightgbm/checkouts/python-3.13/external_libs/fast_double_parser/benchmarks/dependencies/double-conversion'...
Submodule path 'external_libs/fast_double_parser/benchmarks/dependencies/abseil-cpp': checked out 'd936052d32a5b7ca08b0199a6724724aea432309'
Submodule path 'external_libs/fast_double_parser/benchmarks/dependencies/double-conversion': checked out 'f4cb2384efa55dee0e6652f8674b05763441ab09'
Submodule path 'external_libs/fmt': checked out 'f5e54359df4c26b6230fc61d38aa294581393084'

[rtd-command-info] start-time: 2025-01-23T04:04:28.645481Z, end-time: 2025-01-23T04:04:28.730020Z, duration: 0, exit-code: 0
asdf global python miniconda3-4.7.12


[rtd-command-info] start-time: 2025-01-23T04:04:29.623725Z, end-time: 2025-01-23T04:04:29.676355Z, duration: 0, exit-code: 0
cat docs/env.yml
channels:
- nodefaults
- conda-forge
dependencies:
- breathe>=4.35
- python=3.11
- r-base=4.3.2
- r-data.table=1.14.10
- r-jsonlite=1.8.8
- r-knitr=1.45
- r-markdown=1.12
- r-matrix=1.6_4
- r-pkgdown=2.0.7
- r-roxygen2=7.3.2
- scikit-learn>=1.4.0
- sphinx>=6.0
- sphinx_rtd_theme>=2.0
- pip: []
- sphinx
name: docs-env

I do not see any issues reported at https://status.readthedocs.com/

Can you please help me understand what's going wrong? That banner text suggests that it's an internal issue with readthedocs, not a result of my configuration, but I don't have enough information to investigate this further.

[stsewd]

Hi, testing locally, I see the following error

conda env create --quiet --name python-3.13 --file docs/env.yml
Command killed due to timeout or excessive memory consumption

My guess is that the same thing is happening in production, but RTD isn't able to log that error.

Sadly, I'm not familiar enough with conda to suggest something better other than maybe try with a newer version of miniconda https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python

[jameslamb]

Ok thanks! Will try updating the environment and the conda version.

It'd be great if RTD was able to log that error, or if I could configure it to run conda env create without --quiet.

[jameslamb]

Updating the conda env, operating system, and conda version worked... the build is now succeeding 🎉

build link: https://readthedocs.org/projects/lightgbm/builds/26953971/

I changed my project's configuration to use a newer version of conda and a newer operating system:

version: 2
build:
  os: "ubuntu-lts-latest"
  tools:
    python: "mambaforge-latest"

.readthedocs.yaml (click me)

version: 2
build:
  os: "ubuntu-lts-latest"
  tools:
    python: "mambaforge-latest"
conda:
  environment: docs/env.yml
formats:
  - pdf
sphinx:
  builder: html
  configuration: docs/conf.py
  fail_on_warning: true
submodules:
  include: all
  recursive: true

I also updated the dependencies in the conda environment such that it could be solved successfully and without too much runtime or memory usage.

docs/env.yml (click me)

name: docs-env
channels:
  - nodefaults
  - conda-forge
dependencies:
  - breathe>=4.35
  - python=3.12
  - r-base>=4.3.3
  - r-data.table=1.16.4
  - r-jsonlite=1.8.9
  - r-knitr=1.49
  - r-markdown=1.13
  - r-matrix=1.6_5
  - r-pkgdown=2.1.1
  - r-roxygen2=7.3.2
  - scikit-learn>=1.6.1
  - sphinx>=8.1.3,<9
  - sphinx_rtd_theme>=3.0.1,<4

Thanks very much!