tinyhumansai/openhuman · error

agent definition '{}' not found in registry

Error message

agent definition '{}' not found in registry

What it means

resolve_target_definition (src/openhuman/agent/harness/session/builder/factory.rs:1415) is the last-resort miss: the agent id was not in the global AgentDefinitionRegistry, not in the config-backed custom registry (config.agent_registry.entries), and is not "orchestrator" (which may legally fall back to legacy defaults returning Ok(None)). Note the distinct sibling error when registry.is_none(): that one says the registry was never initialized — this one means it was initialized and simply lacks the id.

Source

Thrown at src/openhuman/agent/harness/session/builder/factory.rs:1415

    if agent_id == "orchestrator" {
        // Orchestrator is allowed to be missing from every source (legacy
        // path, tests, pre-startup) — fall back to default behaviour.
        log::debug!(
            "[agent::builder] orchestrator definition not in any registry — using legacy \
             default prompt + filter"
        );
        return Ok(None);
    }

    if registry.is_none() {
        return Err(anyhow::anyhow!(
            "AgentDefinitionRegistry is not initialised — cannot resolve agent '{}'. Call \
             AgentDefinitionRegistry::init_global at startup.",
            agent_id
        ));
    }

    Err(anyhow::anyhow!(
        "agent definition '{}' not found in registry",
        agent_id
    ))
}

fn definition_disallows_tool(disallowed: &[String], name: &str) -> bool {
    disallowed.iter().any(|entry| {
        if let Some(prefix) = entry.strip_suffix('*') {
            name.starts_with(prefix)
        } else {
            entry == name
        }
    })
}

/// Which tool-call dialect a session speaks to its provider.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DispatcherKind {

View on GitHub (pinned to a221052e0d)

Solutions

1. Verify the id against registry.list() (or the debug prompt dump) and fix the typo/rename.
2. If it is a custom agent, define it under config.agent_registry.entries or as a workspace override so one of the two lookup sources finds it.
3. Confirm AgentDefinitionRegistry::init_global ran against the same workspace_dir your session uses (mismatched workspaces load different override sets).
4. If the binary is a slim/feature-gated build, rebuild with the feature set that embeds that agent.
5. Do not shadow with "orchestrator" — only that exact id is allowed to resolve to legacy defaults.

Example fix

// before
let agent = build_session_agent(&config, "integration_agent").await?; // typo
// after
let agent = build_session_agent(&config, "integrations_agent").await?;

fn agent_id_resolves(config: &Config, agent_id: &str) -> bool {
    if let Some(reg) = AgentDefinitionRegistry::global() {
        if reg.get(agent_id).is_some() {
            return true;
        }
    }
    // second source: config-backed custom agents
    crate::openhuman::agent::registry::find_custom_in_config(config, agent_id).is_some()
        || agent_id == "orchestrator" // legacy fallback allowed to resolve to None
}

fn agent_id_resolves(config: &Config, agent_id: &str) -> bool {
    AgentDefinitionRegistry::global().map(|r| r.get(agent_id).is_some()).unwrap_or(false)
        || crate::openhuman::agent::registry::find_custom_in_config(config, agent_id).is_some()
}

match resolve_target_definition(&config, agent_id).await {
    Ok(Some(def)) => Ok(def),
    Ok(None) => Ok(/* orchestrator legacy default build */),
    Err(e) if e.to_string().contains("not found in registry") => {
        // Not a retry case: fix the id (registry.list() / dump-all), register
        // the custom agent in config.agent_registry.entries or a workspace
        // override, or confirm the build embeds it.
    }
    Err(e) => Err(e), // the 'not initialised' sibling needs init_global at startup
}

When it happens

Trigger: Building a session with a typo'd/stale agent_id; an id that existed in a previous version or a different workspace's overrides; a custom id present in neither the harness registry nor config.agent_registry.entries; an agent compiled out by a feature-gated slim build.

Common situations: Persisted thread metadata referencing an agent id deleted by a workspace override cleanup; downstream code hardcoding an agent id that a rename/feature-gate removed; per-workspace overrides not loaded because init_global ran against a different workspace_dir.

Related errors

• integrations_agent definition missing from registry
• integrations_agent definition not in registry
• agent registry rejected after merging workspace overrides fr
• artifact_get: {e}
• artifact_delete: {e}

AI-assisted analysis of tinyhumansai/openhuman@a221052e0d (2026-08-16). Data as JSON: /api/errors/f84f1b7c03fe8cc1. Report an issue: GitHub.