nikivdev/code · error

Could not find agent file for '{}'

Error message

Could not find agent file for '{}'

What it means

This error is thrown by get_agent_content in src/agents.rs when resolving a built-in agent by name. After checking the resolved agent_path (including the failed read already handled just above) no matching agent file can be located for the requested agent name, so the function bails out. It indicates the agent name is not a built-in agent shipped with this binary.

Source

Thrown at src/agents.rs:457

    ];
    if let Some(repo) = gen_repo_from_env() {
        locations.push(Some(repo.join(".opencode/agent")));
    }
    if let Some(repo) = default_gen_repo() {
        locations.push(Some(repo.join(".opencode/agent")));
    }

    for loc in locations.into_iter().flatten() {
        let agent_path = loc.join(format!("{}.md", name));
        if agent_path.exists() {
            return fs::read_to_string(&agent_path).context(format!(
                "failed to read agent file: {}",
                agent_path.display()
            ));
        }
    }

    bail!("Could not find agent file for '{}'", name)
}

/// Get built-in flow agent instructions.
fn get_flow_agent_instructions() -> String {
    r#"You are a Flow-aware agent with full context about flow.toml, tasks, and the Flow CLI.

## Capabilities
- Read and modify flow.toml configuration
- Create, update, and run tasks
- Understand the flow.toml schema and best practices
- Help with CI/CD workflows, dependencies, and project setup

## Guidelines
- Always read the existing flow.toml before making changes
- Preserve existing configuration when adding new items
- Use appropriate task names and descriptions
- Follow TOML formatting conventions
- Enforce Flow env store usage for secrets/tokens (use `f env get` / `f env run`)

View on GitHub (pinned to a747e741ae)

Solutions

1. Run `f agents list` (or check the built-in agent registry) and use an exact agent name.
2. Correct the typo in the agent name passed to copy_agent_instructions.
3. Reinstall/upgrade the Flow CLI so the bundled agent files exist on disk.
4. If a custom agent is intended, place the file where the resolver looks or use the gen-managed agent mechanism instead.

Example fix

// before
f agents copy code-reviewer
// error: Could not find agent file for 'code-reviewer'
// after
f agents list            # discover valid names
cf agents copy reviewer  # use an existing built-in name

let valid = f agents list 2>/dev/null | grep -Fx "$name";
[ -n "$valid" ] && f agents copy "$name"

fn is_known_agent(name: &str, known: &[&str]) -> bool {
    known.iter().any(|k| k == &name)
}

match copy_agent_instructions(name) {
    Err(e) if e.to_string().contains("Could not find agent file") => {
        eprintln!("Unknown agent '{name}'. Run `f agents list`.");
    }
    Err(e) => return Err(e),
    Ok(()) => {}
}

When it happens

Trigger: Calling copy_agent_instructions (e.g. `f agents copy <name>`) with an agent name that does not match any built-in agent file, or when the agent file expected on disk at the resolved agent_path is missing (e.g. a broken installation or stripped binary resources).

Common situations: Typos in the agent name; copying instructions for an agent that exists in a newer Flow version but not the installed one; a corrupted or partially installed CLI where the bundled agent assets were removed.

Related errors

• No prompt provided. Usage: f agents run {} "your prompt here
• Diff bundle not found. Expected {} or pass a path to a bundl
• Template not found: {}
• Source folder does not exist: {}
• Doc file not found: {}.md

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