Hmbown/CodeWhale · error · anyhow::Error

plugin Agent component is unavailable: {}

Error message

plugin Agent component is unavailable: {}

What it means

Fleet agent-profile loading accepts a plugin's Agent component as either a directory of TOML profiles or a single profile file. This error fires when the component path is neither — it does not exist, is a broken symlink, or is something else (fifo/socket). Unlike a malformed profile (which degrades to a warning issue list), a missing component is a hard error because the plugin declared an Agent capability that cannot be loaded at all.

Source

Thrown at crates/tui/src/fleet/profile.rs:249

    Ok((profiles, issues))
}

pub(crate) fn load_plugin_agent_profiles_from_component(
    component: &Path,
    authority: &crate::plugins::types::PluginAuthority,
) -> Result<(Vec<AgentProfile>, Vec<String>)> {
    let (mut profiles, issues) = if component.is_dir() {
        load_agent_profiles_from_dir_tolerant(component, ProfileOrigin::Plugin)?
    } else if component.is_file() {
        match load_agent_profile_file(component) {
            Ok(mut profile) => {
                profile.origin = ProfileOrigin::Plugin;
                (vec![profile], Vec::new())
            }
            Err(error) => (Vec::new(), vec![format!("{error:#}")]),
        }
    } else {
        return Err(anyhow!(
            "plugin Agent component is unavailable: {}",
            component.display()
        ));
    };
    for profile in &mut profiles {
        profile.plugin_authority = Some(authority.clone());
    }
    Ok((profiles, issues))
}

/// Read only the identity-bearing fields from workspace profiles for the
/// authoring collision gate.  Unknown legacy fields are harmless here because
/// no profile behavior is loaded or executed from this representation.
pub fn load_workspace_agent_profile_identities(
    workspace: impl AsRef<Path>,
) -> Result<Vec<AgentProfileIdentity>> {
    let dir = workspace.as_ref().join(WORKSPACE_AGENT_PROFILE_DIR);
    load_agent_profile_identities_from_dir(dir)

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Check the printed path: does it exist relative to the plugin root? Create it, fix the manifest's component path, or ship the missing files.
2. Reinstall or fully extract the plugin; for git-based installs run submodule update / restore missing files.
3. If the plugin should have no agents, remove the Agent component entry from its manifest rather than pointing at nothing.
4. For broken symlinks, restore the link target or replace it with real files.

Example fix

# before: plugin.toml declares a component that is absent
[components]
agents = "agents/"        # plugins/foo/agents/ does not exist

# after: ship the directory or point at the real file
[components]
agents = "agents/"        # plugins/foo/agents/*.toml present

fn plugin_agent_component_usable(path: &Path) -> bool {
    path.is_dir() || path.is_file() // false for missing paths, broken symlinks, specials
}

if !plugin_agent_component_usable(&component) {
    // fail plugin load with a clear message before profile collection
}

fn existing_file_or_dir(p: &Path) -> Option<&Path> {
    (p.is_file() || p.is_dir()).then_some(p)
}

match load_plugin_agent_component(component, authority) {
    Err(e) if e.to_string().contains("plugin Agent component is unavailable") => {
        // plugin packaging defect: skip plugin's agents, report to plugin author; do not crash the app
    }
    other => other?,
}

When it happens

Trigger: A plugin manifest declaring an agents component path that does not exist in the installed plugin (bad relative path, files not shipped, broken symlink), or a plugin directory partially copied/extracted.

Common situations: Plugin packaging bugs omitting the agents folder; plugins installed by git clone with a submodule left uninitialized; manifest paths written for a different plugin layout version; moving/renaming the plugin directory after registration.

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

• duplicate agent profile id {}
• agent profile path {} is not a directory
• agent profile {} tools.posture={other:?} would widen permiss
• agent profile {} may not request allow_shell=true
• agent profile {} may not request trust=true

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/deee73ada13e9495. Report an issue: GitHub.