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.