rust-lang/mdBook · error

{} is reserved for internal use

Error message

{} is reserved for internal use

What it means

When rendering chapters, the handlebars renderer bails if a chapter's source path is "print.md", because that filename is reserved by mdbook for the aggregated print page. Allowing it would collide with the generated print.html output, so the render fails fast with this error.

Source

Thrown at crates/mdbook-html/src/html_handlebars/hbs_renderer.rs:43

    /// Returns a new instance of [`HtmlHandlebars`].
    pub fn new() -> Self {
        HtmlHandlebars
    }

    fn render_chapter(
        &self,
        chapter_tree: &ChapterTree<'_>,
        prev_ch: Option<&Chapter>,
        next_ch: Option<&Chapter>,
        mut ctx: RenderChapterContext<'_>,
    ) -> Result<()> {
        // FIXME: This should be made DRY-er and rely less on mutable state
        let ch = chapter_tree.chapter;

        let path = ch.path.as_ref().unwrap();
        // "print.html" is used for the print page.
        if path == Path::new("print.md") {
            bail!("{} is reserved for internal use", path.display());
        };

        if let Some(ref edit_url_template) = ctx.html_config.edit_url_template {
            let full_path = ctx.book_config.src.to_str().unwrap_or_default().to_owned()
                + "/"
                + ch.source_path
                    .clone()
                    .unwrap_or_default()
                    .to_str()
                    .unwrap_or_default();

            let edit_url = edit_url_template.replace("{path}", &full_path);
            ctx.data
                .insert("git_repository_edit_url".to_owned(), json!(edit_url));
        }

        let mut content = String::new();
        serialize(&chapter_tree.tree, &mut content);

View on GitHub (pinned to dc21064fc2)

Solutions

1. Rename src/print.md to something else (e.g. src/printing.md) and update its SUMMARY.md entry.
2. If the file was accidental, delete it from src/.
3. Search the book for links referencing print.md and update them to the new filename.
4. Rebuild after the rename to confirm rendering succeeds.

Example fix

// before
mv src/print.md src/print-page.md
# SUMMARY.md
- [Print](./print.md)

// after
# SUMMARY.md
- [Print](./print-page.md)

use std::path::Path;
fn assert_no_reserved_files(src: &Path) -> anyhow::Result<()> {
    let print_md = src.join("print.md");
    if print_md.exists() {
        anyhow::bail!("{} is reserved for internal use; rename it", print_md.display());
    }
    Ok(())
}

// guard build invocation for tooling that runs mdbook build
let out = Command::new("mdbook").arg("build").output()?;
if !out.status.success() {
    let msg = String::from_utf8_lossy(&out.stderr);
    if msg.contains("reserved for internal use") {
        eprintln!("rename src/print.md — mdbook reserves it for the print page");
    }
}

When it happens

Trigger: Having a file named print.md inside the book's src/ directory (whether referenced in SUMMARY.md or discovered as a draft/extra chapter) and running mdbook build or mdbook serve with HTML output enabled.

Common situations: Users creating a printable chapter literally named print.md, migration from tools that used print.md as a page name, or copying content files that clash with mdbook's reserved output name.

Related errors

• Command string was empty
• internal error: expected `{lookup_key:?}` to be in root map

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