Read the Docs ".readthedocs.yaml" config invalid in CI

Read the Docs requires a valid .readthedocs.yaml at the repo root. A missing file, a missing build.os/build.tools, or a schema error makes the build fail before installing dependencies.

What this error means

The RTD build fails early with "Invalid .readthedocs.yaml" or "Config validation error", naming the missing or wrong key (often build.os or build.tools).

readthedocs

Problem in your project's configuration. Invalid ".readthedocs.yaml":
config.build.os: required key not provided

Common causes

Missing required build keys

The v2 config requires build.os and build.tools; omitting them fails schema validation.

A malformed or misplaced config file

The file is not at the repo root, has invalid YAML, or uses keys not in the schema, so RTD rejects it.

How to fix it

Provide a valid v2 config

Place .readthedocs.yaml at the repository root.
Set version: 2, a build.os, and build.tools versions.
Declare your docs builder (sphinx or mkdocs).

.readthedocs.yaml

version: 2
build:
  os: ubuntu-24.04
  tools:
    python: "3.12"
sphinx:
  configuration: docs/conf.py

Validate the YAML

Lint the file so a YAML syntax error does not masquerade as a schema problem.

Terminal

python -c "import yaml,sys; yaml.safe_load(open('.readthedocs.yaml'))"

How to prevent it

Keep .readthedocs.yaml at the repo root with version: 2.
Always set build.os and build.tools.
Lint the YAML before pushing.