Sphinx "Theme error: no theme named" build failure in CI

Sphinx resolved html_theme from conf.py and could not find a registered theme by that name. The theme package (or its entry point) is not installed in the build environment.

What this error means

sphinx-build fails with "Theme error: no theme named 'X' found (missing theme.toml?)" or "no theme named 'X' found", naming the value set in html_theme.

Theme error:
no theme named 'furo' found (missing theme.toml?)

Common causes

The theme package is not installed

conf.py sets html_theme = "furo" but the furo distribution is not in the runner environment, so Sphinx cannot register it.

A theme name and package name mismatch

The configured theme name does not match what the installed package registers, so the lookup returns nothing.

How to fix it

Install the theme package

1. Find the theme value in html_theme in conf.py.
2. Add the matching theme distribution to docs requirements.
3. Install requirements and rebuild.

pip install furo
sphinx-build -b html docs docs/_build/html

Confirm the registered theme name

Use the exact name the theme documents for html_theme; some packages register a name different from the pip distribution.

# conf.py
html_theme = "furo"

How to prevent it

• Keep the theme package in your docs requirements file.
• Match html_theme to the name the theme registers.
• Pin the theme version for reproducible builds.

Related guides