rust-lang/mdBook · error

The BookBuilder should always create a valid book. If you…

Error message

The BookBuilder should always create a valid book. If you are seeing this it is a bug and should be reported.

What it means

BookBuilder::build() calls MDBook::load() after creating the book skeleton; if loading the freshly created book fails it logs the error and panics, stating this indicates an mdbook bug. It is an internal invariant check, not an expected user-facing failure.

Solutions

1. Read the logged error above the panic for the underlying cause and fix it (permissions, disk space)
2. Check that book.toml and src/SUMMARY.md were created and are valid
3. Retry mdbook init; if it persists with valid inputs, report the bug at the mdbook issue tracker

catch_unwind(|| builder.build()).unwrap_or_else(|_| {
    // inspect book.toml / SUMMARY.md in root and report the bug
    std::process::exit(1);
});

When it happens

Trigger: MDBook::load failing immediately after init — typically because the generated book.toml or SUMMARY.md could not be parsed/written (disk errors, permission problems, or a genuine mdbook bug).

Common situations: Running `mdbook init` on a filesystem with permission issues or full disk; a book.toml produced by templates that fails to deserialize; actual mdbook bugs.

Related errors

• ignore root canonicalize error
• ignore root canonicalize error
• internal error: expected empty tag stack. path
• internal error: expected empty tag stack. path
• internal error: expected

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

Appendix: source

Thrown at crates/mdbook-driver/src/init.rs:90

        if self.create_gitignore {
            self.build_gitignore()
                .with_context(|| "Unable to create .gitignore")?;
        }

        if self.copy_theme {
            self.copy_across_theme()
                .with_context(|| "Unable to copy across the theme")?;
        }

        self.write_book_toml()?;

        match MDBook::load(&self.root) {
            Ok(book) => Ok(book),
            Err(e) => {
                error!("{}", e);

                panic!(
                    "The BookBuilder should always create a valid book. If you are seeing this it \
                     is a bug and should be reported."
                );
            }
        }
    }

    fn write_book_toml(&self) -> Result<()> {
        debug!("Writing book.toml");
        let book_toml = self.root.join("book.toml");
        let cfg =
            toml::to_string(&self.config).with_context(|| "Unable to serialize the config")?;

        fs::write(&book_toml, cfg)?;
        Ok(())
    }

    fn copy_across_theme(&self) -> Result<()> {

View on GitHub (pinned to dc21064fc2)