{"record":{"id":"bf113de42f2e95dc","repo":"rust-lang/mdBook","slug":"the-bookbuilder-should-always-create-a-valid-book","errorCode":null,"errorMessage":"The BookBuilder should always create a valid book. If you are seeing this it is a bug and should be reported.","messagePattern":"The BookBuilder should always create a valid book\\. If you are seeing this it is a bug and should be reported\\.","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/mdbook-driver/src/init.rs","lineNumber":90,"sourceCode":"\n        if self.create_gitignore {\n            self.build_gitignore()\n                .with_context(|| \"Unable to create .gitignore\")?;\n        }\n\n        if self.copy_theme {\n            self.copy_across_theme()\n                .with_context(|| \"Unable to copy across the theme\")?;\n        }\n\n        self.write_book_toml()?;\n\n        match MDBook::load(&self.root) {\n            Ok(book) => Ok(book),\n            Err(e) => {\n                error!(\"{}\", e);\n\n                panic!(\n                    \"The BookBuilder should always create a valid book. If you are seeing this it \\\n                     is a bug and should be reported.\"\n                );\n            }\n        }\n    }\n\n    fn write_book_toml(&self) -> Result<()> {\n        debug!(\"Writing book.toml\");\n        let book_toml = self.root.join(\"book.toml\");\n        let cfg =\n            toml::to_string(&self.config).with_context(|| \"Unable to serialize the config\")?;\n\n        fs::write(&book_toml, cfg)?;\n        Ok(())\n    }\n\n    fn copy_across_theme(&self) -> Result<()> {","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/rust-lang/mdBook/blob/dc21064fc21d955a0e1f67e65e336883c3e5260b/crates/mdbook-driver/src/init.rs#L72-L108","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch_unwind(|| builder.build()).unwrap_or_else(|_| {\n    // inspect book.toml / SUMMARY.md in root and report the bug\n    std::process::exit(1);\n});","preventionTips":["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"],"tags":["panic","init","invariant"],"backgroundTag":"unexpected-invariant-violation","analyzedSha":"dc21064fc21d955a0e1f67e65e336883c3e5260b","analyzedAt":"2026-09-01T10:15:12.134Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}