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

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.

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)

Solutions

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

Defensive patterns

Strategy: fallback

Try / catch

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

Prevention

Verify disk space and write permissions before mdbook init
Check that generated book.toml and src/SUMMARY.md are valid after init
If reproducible with a minimal book, file a bug at the mdbook repository

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

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