nikivdev/code · error · anyhow::Error

Unable to resolve docs for {}

Error message

Unable to resolve docs for {}

What it means

open_project_docs maps the current project root to its docs by checking whether the path lives under ~/code or ~/org (via project_docs_for_root). If the project root is under neither known root, it cannot resolve a docs hub entry and bails with the project path in the message.

Source

Thrown at src/docs.rs:844

            .context("failed to invoke kill")?;
        return Ok(());
    }

    #[cfg(windows)]
    {
        Command::new("taskkill")
            .args(["/PID", &pid.to_string(), "/F"])
            .status()
            .context("failed to invoke taskkill")?;
        Ok(())
    }
}

fn open_project_docs(project_root: &Path) -> Result<()> {
    let code_root = config::expand_path("~/code");
    let org_root = config::expand_path("~/org");
    let Some(project) = project_docs_for_root(project_root, &code_root, &org_root, false) else {
        bail!("Unable to resolve docs for {}", project_root.display());
    };

    let hub_opts = DocsHubOpts {
        host: "127.0.0.1".to_string(),
        port: 4410,
        hub_root: "~/.config/flow/docs-hub".to_string(),
        template_root: DEFAULT_DOCS_TEMPLATE_ROOT.to_string(),
        code_root: "~/code".to_string(),
        org_root: "~/org".to_string(),
        no_ai: true,
        no_open: true,
        sync_only: false,
    };
    ensure_docs_hub_daemon_with_focus(&hub_opts, Some(project_root))?;

    if !(project_root.starts_with(&code_root) || project_root.starts_with(&org_root)) {
        println!(
            "Docs hub only indexes ~/code and ~/org; {} may not be available.",

View on GitHub (pinned to a747e741ae)

Solutions

1. Move or symlink the project under ~/code or ~/org so path resolution succeeds (ln -s ~/work/myrepo ~/code/myrepo)
2. Create the expected roots (mkdir -p ~/code ~/org) if the machine is fresh and relocate projects there
3. Check for symlinks/case mismatches making the resolved path differ; use the real path for your checkout
4. If a custom root is supported by the tool configuration, add your checkout directory to it

Example fix

// before
$ cd ~/work/myrepo && mytool docs open
Error: Unable to resolve docs for /home/me/work/myrepo
// after
$ mkdir -p ~/code && ln -s ~/work/myrepo ~/code/myrepo
$ cd ~/code/myrepo && mytool docs open
Opening docs hub for myrepo...

let root = std::fs::canonicalize(cwd)?;
let under = |base: &str| root.starts_with(config::expand_path(base));
if !under("~/code") && !under("~/org") {
    eprintln!("{} is not under ~/code or ~/org; docs cannot be resolved", root.display());
    return;
}
run_docs_open()?;

match run(&cmd) {
    Err(e) if e.to_string().contains("Unable to resolve docs for") => {
        eprintln!("move or symlink the project under ~/code or ~/org, then retry");
    }
    Err(e) => return Err(e),
    Ok(()) => {}
}

When it happens

Trigger: Calling the `run`/docs-open command from a project directory outside ~/code and ~/org — e.g. repos in ~/src, ~/work, /tmp, or a custom checkout directory — or when project_docs_for_root cannot match the root even under those trees.

Common situations: Developer keeps repositories in a non-default location (~/dev, ~/projects); symlinks confusing path canonicalization; fresh machine where ~/code/~/org don't exist yet; CI running from arbitrary build directories.

Related errors

• Docs template root not found: {}
• timeout must be a positive finite number
• missing CLOUDFLARE_API_TOKEN; set it in shell env or Flow pe
• missing CLOUDFLARE_ACCOUNT_ID; set it in shell env or Flow p
• Flow Codex wrapper is missing at {}; build or sync Flow firs

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