jupyter-book warnings treated as errors (-W) in CI

jupyter-book builds with Sphinx underneath. Passing -W (or setting warningiserror) makes Sphinx exit non-zero on any warning, so broken cross-references, missing toc entries, or duplicate labels that would normally be tolerated fail the CI build.

What this error means

jupyter-book build -W exits non-zero with "build finished with problems, N warnings (with warnings treated as errors)" and lists each warning that was promoted.

jupyter-book

WARNING: 'myst' cross-reference target not found: 'fig-results'
build finished with problems, 1 warning (with warnings treated as errors).

Common causes

A real documentation warning under strict mode

A broken link, missing reference, or duplicate label produces a Sphinx warning that -W turns into a build failure.

Strict mode enabled to keep docs clean

The CI deliberately runs with warnings-as-errors so any new warning blocks the merge.

How to fix it

Fix the underlying warning

Read each warning the build lists.
Repair the broken reference, link, or label it names.
Re-run the strict build until it reports zero warnings.

Terminal

jupyter-book build -W .

Keep strict mode but suppress a known false positive

If a specific warning is genuinely expected, suppress just that type in _config.yml rather than dropping -W everywhere.

_config.yml

sphinx:
  config:
    suppress_warnings: ["myst.xref_missing"]

How to prevent it

Build with -W locally so warnings surface before CI.
Fix warnings as they appear instead of letting them accumulate.
Suppress only specific, justified warning types, not all of them.