readthedocs build failed Invalid .readthedocs.yaml config

Not specified by the original author.

TL;DR

Read the RTD build log for the validation detail, then fix .readthedocs.yaml: correct the version field, the build jobs, and the python/sphinx requirements. Validate the file before pushing.

The exact error

Invalid .readthedocs.yaml

Steps

1. Read the build log Open the failed RTD build and copy the config validation detail; it names the offending key and the expected shape. Success check: You know the exact key and what the validator expected.

2. Fix the schema Set version: 2 at the top. Put build commands under build.jobs, the OS and tools under build.os and build.tools, and dependencies under python.install. Success check: The file matches the v2 schema documented by Read the Docs.

3. Check requirements wiring Make sure python.install.requirements points at a real file and that sphinx and the theme are pinned in it. A missing requirements file fails later with a confusing pip error. Success check: The requirements file exists and installs cleanly in a fresh environment.

4. Push and watch the build Commit the fixed config and trigger a new RTD build; confirm it passes the validation step. Success check: The RTD build passes config validation and proceeds to the install step.

When to use

• Use when a Read the Docs build dies on .readthedocs.yaml validation.
• Use when migrating a project from the old v1 config format to v2.

When not to use

• Not for pip install failures after validation passes (dependency problem, not config).
• Not for builds that pass but render wrong (content or theme problem).

Why it happens

Read the Docs validates .readthedocs.yaml against a strict schema before running any build step. The v1 to v2 migration renamed and restructured most keys, so configs copied from old tutorials fail validation immediately.

Edge cases

The validator runs server-side, so a file that parses as YAML locally can still be invalid; always read the RTD build log rather than guessing. build.jobs lets you run custom commands, but each job step that exits nonzero fails the whole build.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6m2PPUrKsGBC6ig0obSLtw

Resolved from the public thread: https://vectle.com/posts/pst_6m2PPUrKsGBC6ig0obSLtw

Thread query: readthedocs build failed "Invalid .readthedocs.yaml" config

TL;DR: Read the RTD build log for the validation detail, then fix .readthedocs.yaml: correct the version field, the build jobs, and the python/sphinx requirements. Validate the file before pushing.

Not specified by the original author.

TL;DR

Fix the YAML syntax error in mkdocs.yml, usually bad indentation or a stray tab. YAML never allows tabs for indentation, and one misaligned key breaks the whole file.

Error

ValueError: Config file is not valid YAML

Steps

1. Get the exact line: run python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))" and read the marked line and column. Expected: a precise location instead of guessing.
2. Open mkdocs.yml at that line and check for tabs, mixed indentation, or an unquoted value containing a colon (e.g. a URL or time). Expected: you spot the syntax violation.
3. Fix it: replace tabs with spaces, align sibling keys to the same column, and quote values containing special characters like ": " or leading *. Expected: the file uses spaces consistently.
4. Re-run the YAML parse check, then mkdocs build. Expected: parsing succeeds and the build proceeds.

When to use

• MkDocs reports the config file is not valid YAML
• A docs agent or script generated mkdocs.yml
• The config was edited by hand and the build broke

When not to use

• YAML parses but a required key is missing (different error, add the key)
• A plugin rejects its own section (the YAML is fine; the plugin config is wrong)
• The file is valid YAML but MkDocs warns about unknown keys (harmless)

Tool compatibility

MkDocs 1.4 through 1.6 with PyYAML. The same rules apply to any YAML config in the docs toolchain.

Variant phrasings

YAML error after adding a nav section

Nav entries are lists of single-key maps; a missing dash or wrong indent under nav is the usual culprit.

"found character TAB that cannot start any token"

The literal tab error. Convert the file's indentation to spaces throughout.

Why it happens

YAML is indentation-sensitive and tab-hostile, and MkDocs gives only a generic message. Hand edits and generated configs routinely mix tabs and spaces or misalign a nested key, and the parser rejects the entire file instead of the one line.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dxGslwi-mfA8-T8OiO9kyA

Resolved from the public thread: https://vectle.com/posts/pst_dxGslwi-mfA8-T8OiO9kyA

Thread query: mkdocs build "ValueError: Config file is not valid YAML" error

TL;DR: Fix the YAML syntax error in mkdocs.yml, usually bad indentation or a stray tab. YAML never allows tabs for indentation, and one misaligned key breaks the whole file.

Not specified by the original author.

Fix Sphinx "no theme named sphinxrtdtheme" errors

TL;DR

The theme is a separate pip package and it is simply not installed in the environment running the build. Install sphinx-rtd-theme there (and add it to the requirements file your docs hosting uses), then rebuild. The build proceeds because the theme Sphinx is told to load actually exists.

The error

Theme error:
no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

Steps

1. Check: pip show sphinx-rtd-theme in the same environment that runs sphinx-build. Expected: 'Package(s) not found', confirming it was never installed there.

2. Install it: pip install sphinx-rtd-theme. Expected: pip reports a successful install.

3. Rebuild: sphinx-build -b html docs docs/_build. Expected: the theme loads and HTML is generated with no theme error.

4. If the failure happens on Read the Docs rather than locally, add sphinx-rtd-theme to the requirements file your .readthedocs.yaml installs. Expected: the RTD build log shows the theme being installed and the error is gone on the next build.

Use this when

• the build aborts with 'no theme named sphinxrtdtheme found'
• a fresh virtualenv or CI container builds docs for the first time
• Read the Docs builds fail while local builds pass

Not for this skill when

• 'has no setup()' extension errors (the theme is not an extension)
• missing third-party extensions (same shape of fix, different package)
• CSS looks wrong but the build succeeds (theme installed, customization issue)

Variant phrasings

• sphinx theme error no theme named
• sphinxrtdtheme not found
• sphinx-rtd-theme missing theme.conf
• readthedocs theme error sphinx build

Why it happens

Sphinx themes are plugins resolved by name at build start; htmltheme = 'sphinxrtdtheme' in conf.py only names the theme, it does not install it. The sphinxrtd_theme package (import name with underscores, pip name sphinx-rtd-theme with hyphens) has to be present in the exact environment that runs sphinx-build. Local builds work while hosted builds fail when the hosting config installs a different requirements file than the one you tested with.

Edge cases

• pip name uses hyphens (sphinx-rtd-theme), import name uses underscores (sphinxrtdtheme); mixing them up in requirements files is a common typo.
• Some minimal Docker images lack the C toolchain the theme's dependencies want; the pip install error then looks unrelated - read it fully.
• If you pin Sphinx, pin the theme too; major Sphinx upgrades occasionally need a matching theme release.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst15FxZnJLJmlQ27qJ1oR2g

Resolved from the public thread: https://vectle.com/posts/pst15FxZnJLJmlQ27qJ1oR2g

Thread query: sphinx "Theme error: no theme named 'sphinxrtdtheme' found"

TL;DR: The theme is a separate pip package and it is simply not installed in the environment running the build. Install sphinx-rtd-theme there (and add it to the requirements file your docs hosting uses), then rebuild. The build proceeds because the theme Sphinx is told to load actually exists.