rust-lang/mdBook · error

Chapter not found: {}

Error message

Chapter not found: {}

What it means

When `mdbook test --chapter <name>` is given a chapter name, test_chapter() tracks whether any tested item matched it; if no chapter matched (after tests ran without failures) it bails with "Chapter not found".

Source

Thrown at crates/mdbook-driver/src/mdbook.rs:341

                    .with_context(|| "failed to execute `rustdoc`")?;

                if !output.status.success() {
                    failed = true;
                    eprintln!(
                        "ERROR rustdoc returned an error:\n\
                        \n--- stdout\n{}\n--- stderr\n{}",
                        String::from_utf8_lossy(&output.stdout),
                        String::from_utf8_lossy(&output.stderr)
                    );
                }
            }
        }
        if failed {
            bail!("One or more tests failed");
        }
        if let Some(chapter) = chapter {
            if !chapter_found {
                bail!("Chapter not found: {}", chapter);
            }
        }
        Ok(())
    }

    /// The logic for determining where a backend should put its build
    /// artefacts.
    ///
    /// If there is only 1 renderer, put it in the directory pointed to by the
    /// `build.build_dir` key in [`Config`]. If there is more than one then the
    /// renderer gets its own directory within the main build dir.
    ///
    /// i.e. If there were only one renderer (in this case, the HTML renderer):
    ///
    /// - build/
    ///   - index.html
    ///   - ...
    ///

View on GitHub (pinned to dc21064fc2)

Solutions

  1. Use the exact chapter name/title as it appears in SUMMARY.md
  2. Verify the chapter contains Rust code blocks to test
  3. Run `mdbook test` without --chapter to list/run everything and confirm the chapter exists

Example fix

// before
$ mdbook test --chapter "getting started"
// after
$ mdbook test --chapter "Getting Started"
Defensive patterns

Strategy: validation

Validate before calling

// before running: confirm the chapter title exists in SUMMARY.md
let titles: Vec<&str> = std::fs::read_to_string("src/SUMMARY.md")?.lines().collect();
assert!(titles.iter().any(|l| l.contains(chapter_name)), "chapter not in SUMMARY.md");

Try / catch

if let Err(e) = book.test(&[], Some(chapter), None) {
    if e.to_string().starts_with("Chapter not found") {
        eprintln!("check the exact chapter title in SUMMARY.md");
    }
    std::process::exit(1);
}

Prevention

When it happens

Trigger: Running `mdbook test --chapter NAME` where NAME does not match any chapter's name (or the matching chapter contains no Rust code blocks so it is never visited).

Common situations: Typo in the chapter name; using the file path instead of the chapter title; renamed chapters after restructuring the book.

Related errors

AI-assisted analysis of rust-lang/mdBook@dc21064fc2 (2026-09-01). Data as JSON: /api/errors/a5f8b0ed50ac54ef. Report an issue: GitHub.