What causes "Doc file not found: {}.md" in nikivdev/code?

List the docs directory to find the correct slug, then retry with the exact name

nikivdev/code · error · anyhow::Error

Doc file not found: {}.md

Error message

Doc file not found: {}.md

What it means

Raised by `edit_doc` (src/docs.rs:249) when the requested doc `<name>.md` does not exist under the docs directory. The tool checks `doc_path.exists()` before launching `$EDITOR` (default vim) and bails with the exact filename it looked for.

Source

Thrown at src/docs.rs:249

    fs::write(&marker_path, format!("{} ({})\n", now, head))?;

    println!("\n✓ Sync marker updated");
    println!("\nTo fully sync docs, use an AI assistant to:");
    println!("  1. Review recent commits");
    println!("  2. Update changelog.md with new features");
    println!("  3. Update commands.md if CLI changed");
    println!("  4. Update architecture.md if structure changed");

    Ok(())
}

/// Open a doc file in the editor.
fn edit_doc(docs_dir: &Path, name: &str) -> Result<()> {
    let doc_path = docs_dir.join(format!("{}.md", name));

    if !doc_path.exists() {
        bail!("Doc file not found: {}.md", name);
    }

    let editor = std::env::var("EDITOR").unwrap_or_else(|_| "vim".to_string());

    Command::new(&editor)
        .arg(&doc_path)
        .status()
        .with_context(|| format!("failed to open {} with {}", doc_path.display(), editor))?;

    Ok(())
}

fn review_pending(limit: usize) -> Result<()> {
    let reviewed = codex_session_docs::review_pending_entries(limit)?;
    println!(
        "Reviewed {} pending session-doc entr{}",
        reviewed,
        if reviewed == 1 { "y" } else { "ies" }

View on GitHub (pinned to a747e741ae)

Solutions

List the docs directory to find the correct slug, then retry with the exact name
Create the doc first (f docs new/add) if it does not exist
Check case sensitivity — file names must match exactly on Linux
Confirm you are in the intended project so docs_dir resolves correctly

Example fix

// before
f docs edit archtecture
error: Doc file not found: archtecture.md
// after
ls .ai/docs/
f docs edit architecture

Defensive patterns

Strategy: validation

Validate before calling

let doc = format!(".ai/docs/{name}.md");
if !Path::new(&doc).is_file() {
    anyhow::bail!("unknown doc slug '{name}'; list .ai/docs/ first");
}
f_docs_edit(name)?;

Type guard

fn doc_exists(docs_dir: &Path, name: &str) -> bool {
    docs_dir.join(format!("{name}.md")).is_file()
}

Try / catch

match f_docs_edit(name) {
    Err(e) if e.to_string().starts_with("Doc file not found") => {
        eprintln!("{e:#}; available: {:?}", list_doc_slugs(docs_dir));
        // optionally create the doc then retry
    }
    other => other?,
}

Prevention

List docs before editing to confirm exact slugs
Match case exactly — Linux filesystems are case-sensitive
Create missing docs with the docs add/new command first
Use tab-completion or a slug list in wrapper scripts

When it happens

Trigger: Calling `f docs edit <name>` (edit_doc -> run) where `docs_dir/<name>.md` does not exist: the doc was never created, the name is misspelled, the name includes an unintended subdirectory or a wrong case, or the docs directory points at the wrong project.

Common situations: Typo in the doc slug, editing a doc created by a teammate under a different name, case-sensitivity on Linux filesystems (README vs readme), or running from a different checkout where the doc was never committed.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/493b6f69d583c919. Report an issue: GitHub.