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.

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)

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/
• Flow Codex wrapper is missing at {}; build or sync Flow firs
• session is not eligible for promotion
• Doc file not found: {}.md
• docs/ exists but is a file: {}

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