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

By Kaveh Alemi·Latchkey

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?)

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

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"

Make the build reproducible before you debug it

• Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
• Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
• Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
• Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

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.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation