rust-lang/mdBook · critical

internal error: expected `{lookup_key:?}` to be in root map

Error message

internal error: expected `{lookup_key:?}` to be in root map (chapter path is `{html_path:?}`)

What it means

During print-page rendering, mdbook-html rewrites links (rewrite_links) and maps each link target path to its chapter's root identifier using a prebuilt path_to_root_id map. If a lookup key is missing from that map and no earlier is_a_chapter check matched, the code reaches a state it believes impossible and panics with this internal-error message. It indicates a book structure or link target the renderer did not account for, not a user-facing recoverable condition.

Source

Thrown at crates/mdbook-html/src/html/print.rs:204

                        match id_remap.get(&lookup_key) {
                            Some(id_map) => match id_map.get(&anchor_id) {
                                Some(new_id) => new_id.clone(),
                                None => anchor_id,
                            },
                            None => {
                                // Assume the anchor goes to some non-remapped
                                // ID that already exists.
                                anchor_id
                            }
                        }
                    }
                    None => match path_to_root_id.get(&lookup_key) {
                        Some(id) => id.to_string(),
                        None => {
                            // This should be guaranteed that either the
                            // chapter itself is in the map (for anchor-only
                            // links), or the is_a_chapter check above.
                            panic!(
                                "internal error: expected `{lookup_key:?}` to be in \
                                 root map (chapter path is `{html_path:?}`)"
                            );
                        }
                    },
                };
                el.insert_attr(attr, format!("#{id}").into());
            }
        }
    }
}

View on GitHub (pinned to dc21064fc2)

Solutions

1. Fix the link in the offending markdown so its target path corresponds to a chapter declared in SUMMARY.md.
2. Add the target file to SUMMARY.md as a chapter (or draft) so it gets an entry in the root map.
3. Remove or rewrite links that point to non-chapter assets; reference assets via relative paths that resolve to real chapter pages.
4. If reproducible with a minimal book, report it as a bug to the mdbook repository since this is an intended-impossible panic.

Example fix

// before (src/intro.md)
See [details](details.md#section).

// after — ensure details.md is a chapter in SUMMARY.md:
// SUMMARY.md
- [Intro](./intro.md)
- [Details](./details.md)
// and keep the link relative and correct:
See [details](./details.md#section).

fn check_links_are_chapters(src_dir: &Path, summary_chapters: &HashSet<PathBuf>) -> Result<()> {
    for md in markdown_files(src_dir)? {
        for target in extract_relative_link_targets(&md)? {
            let resolved = md.parent().unwrap().join(&target).with_extension("md");
            if !summary_chapters.contains(&resolved) {
                bail!("link target {} is not a chapter in SUMMARY.md", resolved.display());
            }
        }
    }
    Ok(())
}

// run rendering in a worker and capture the panic
let result = std::panic::catch_unwind(|| render_print_page(&ctx));
if result.is_err() {
    eprintln!("print-page rendering failed: check that every link target is a chapter in SUMMARY.md");
}

When it happens

Trigger: Rendering the print page (print.html) via render_print_page while a document contains a link (relative path or anchor-only link) whose resolved path is absent from path_to_root_id — e.g. a link pointing at a non-chapter file in src/ or an anchor link to a chapter excluded from the map.

Common situations: A SUMMARY.md listing or linking to files outside the chapter hierarchy, custom HTML in markdown linking to files not registered as chapters, generated/symlinked pages in src/ that never got SUMMARY entries, or partially-built books where chapters were removed while stale links remained.

Related errors

• `{}` unexpected Html event: {html}
• internal error: expected empty tag stack. path: `{}` node=
• invalid key `{name}`
• The BookBuilder should always create a valid book. If you ar
• pop too far processing `{}`

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