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

By Kaveh Alemi·Latchkey

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

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

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

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.

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.

Frequently asked questions

Related guides

References

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