Sphinx "WARNING ... treated as error" (-W) build failure in CI

Sphinx was run with -W, which promotes every warning to an error. The build aborts on the first warning and prints the underlying message (a broken reference, a duplicate label, an undefined substitution) on the line above.

What this error means

sphinx-build stops with "Warning, treated as error:" followed by the real warning text, and the job exits non-zero even though pages rendered.

sphinx-build

Warning, treated as error:
docs/usage.rst:42:undefined label: 'installation' (if the link has no caption the label must precede a section header)

Common causes

The build runs with -W (warnings as errors)

CI invokes sphinx-build -W (often via make html SPHINXOPTS=-W), so any warning that locally only printed now fails the build.

A genuine warning is present

A broken cross-reference, duplicate label, missing toctree entry, or undefined substitution emits a warning that -W escalates to a hard error.

How to fix it

Read and fix the underlying warning

Read the message printed directly under "Warning, treated as error:".
Fix the source it points to (correct the reference, remove the duplicate label, add the missing toctree entry).
Re-run the build; it now passes with -W still enabled.

Terminal

sphinx-build -W -b html docs docs/_build/html

Keep -W but allow known-noisy warnings

If a specific warning category is expected, suppress only that one rather than dropping -W, so real regressions still fail the build.

conf.py

# conf.py
suppress_warnings = ["ref.python"]

How to prevent it

Run sphinx-build -W locally so warnings surface before CI.
Fix warnings at the source instead of removing -W.
Use suppress_warnings narrowly for categories you accept.