nikivdev/code · error · anyhow::Error

Docs template not found at

Error message

Docs template not found at {}

What it means

Raised by `create_docs_scaffold_at` (src/docs.rs:361) when the docs directory already exists (without `force`) and the configured docs template directory — `expand_path(DEFAULT_DOCS_TEMPLATE_ROOT)` joined with `HUB_CONTENT_ROOT` — cannot be found. The non-force path merges template content into the existing docs dir, which is impossible without the template.

Solutions

1. Verify the template path printed in the message exists (ls the expanded template root) and reinstall/restore the template assets if missing
2. Re-run with force (`--force`) if you don't need the template merge — note this skips merging template content
3. Correct DEFAULT_DOCS_TEMPLATE_ROOT / template config to the actual template location
4. Reinstall or upgrade the tool so the bundled template is present

Example fix

// before
# template root removed by cleanup
error: Docs template not found at ~/.f/templates/hub/docs
// after
f setup --templates   # or reinstall the tool to restore templates
f setup

let tpl = dirs::home_dir().unwrap().join(".f/templates/hub/docs"); // match your template root
if !tpl.is_dir() {
    anyhow::bail!("docs template missing at {}; reinstall the tool or pass --force", tpl.display());
}

fn template_available(template_root: &Path, content_root: &str) -> bool {
    template_root.join(content_root).is_dir()
}

match f_setup() {
    Err(e) if e.to_string().starts_with("Docs template not found") => {
        eprintln!("{e:#}; reinstalling templates or using --force");
        reinstall_templates().or_else(|_| f_setup_force())?;
    }
    other => other?,
}

When it happens

Trigger: Running docs scaffold/`f setup` into an existing docs/ directory while the template root is missing: the hub/template package was never installed, the template root path in config points elsewhere or contains an unexpanded `~`/bad path, or a template version change removed HUB_CONTENT_ROOT.

Common situations: Custom template-root config after a tool upgrade, template deleted by a cleanup, installing the tool without its template assets, or running with HOME set to a location without the template.

Related errors

• No docs directory. Run `f setup` to create .ai/docs/
• Doc file not found: .md
• docs/ exists but is a file
• Flow Codex wrapper is missing at
• session is not eligible for promotion

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

Appendix: source

Thrown at src/docs.rs:361

                cwd.join(expanded)
            }
        }
        None => project_root.to_path_buf(),
    };
    create_docs_scaffold_at(&target_root, opts.force)
}

pub fn create_docs_scaffold_at(project_root: &Path, force: bool) -> Result<()> {
    let docs_dir = project_root.join(PROJECT_DOCS_DIR);
    if docs_dir.exists() {
        if docs_dir.is_file() {
            bail!("docs/ exists but is a file: {}", docs_dir.display());
        }
        if !force {
            let template_root = config::expand_path(DEFAULT_DOCS_TEMPLATE_ROOT);
            let template_docs = template_root.join(HUB_CONTENT_ROOT);
            if !template_docs.exists() {
                bail!("Docs template not found at {}", template_docs.display());
            }
            merge_docs_scaffold(&docs_dir, &template_docs)?;
            ensure_index_file(&docs_dir, "Docs")?;
            println!(
                "Docs already exists; merged template into {}",
                docs_dir.display()
            );
            return Ok(());
        }
        fs::remove_dir_all(&docs_dir)
            .with_context(|| format!("failed to remove {}", docs_dir.display()))?;
    }

    let template_root = config::expand_path(DEFAULT_DOCS_TEMPLATE_ROOT);
    let template_docs = template_root.join(HUB_CONTENT_ROOT);
    if !template_docs.exists() {
        bail!("Docs template not found at {}", template_docs.display());
    }

View on GitHub (pinned to a747e741ae)