jupyter-book "TocError" / bad _toc.yml in CI

By Daniel Zoghalchali·Latchkey

jupyter-book reads _toc.yml to assemble the book. If the file references a document that does not exist, omits a required key, or uses an unknown format, the build aborts while parsing the table of contents and names the offending entry.

What this error means

jupyter-book build (or jb build) fails with a table-of-contents error such as "Toc file ... does not exist", "Could not find document", or a validation error about the format/root keys in _toc.yml.

sphinx_external_toc.parsing.MalformedError: '_toc.yml': 'root' key is required
jupyter-book build: ERROR: Couldn't find a file called 'intro' referenced in _toc.yml

Common causes

A referenced document does not exist

An entry in _toc.yml points at a file path that is missing from the source tree, so the toc cannot resolve it.

An invalid or incomplete _toc.yml structure

A missing root, an unknown format, or wrong indentation makes the external-toc parser reject the file.

How to fix it

Fix the toc entries and structure

1. Read which document or key the error names.
2. Correct the file path or add the missing root/format key.
3. Re-run the build to confirm the toc parses.

format: jb-book
root: intro
chapters:
  - file: notebooks/analysis

Validate the toc before building

Check that every file referenced in _toc.yml exists in the repository checkout used by CI.

jupyter-book build .

How to prevent it

• Keep _toc.yml paths in sync with the files in the repo.
• Include the required format and root keys.
• Build the book locally before pushing to catch toc errors.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation