google-gemini/gemini-cli · error

Subagent ' ' not found.

Error message

Subagent '${params.agent_name}' not found.

What it means

AgentTool.createInvocation throws when the AgentRegistry returned no definition for params.agent_name. The tool validates that a subagent is registered before mapping parameters and building a DelegateInvocation, so an unknown name fails fast rather than producing a confusing downstream error. The value comes from the model's tool call, constrained only by the schema's 'string' type.

Solutions

1. Verify the agent is listed by the registry (inspect Config.getAgentRegistry().getDefinition(name)).
2. Check agent load logs / startup errors for AgentLoadError on that file.
3. Correct the agent_name in the tool call to match the frontmatter 'name' field exactly (case-sensitive).
4. Ensure the agents directory is configured and the target .md file passes validation.

Example fix

// before - model calls agent tool with a misspelled name
{ agent_name: 'resercher', prompt: '...' }

// after
{ agent_name: 'researcher', prompt: '...' }

const registry = config.getAgentRegistry();
if (!registry.getDefinition(requestedName)) {
  const known = registry.listDefinitions().map((d) => d.name);
  throw new Error(`Unknown subagent '${requestedName}'. Known: ${known.join(', ')}`);
}

When it happens

Trigger: The model emitted an agent_name not present in the registry; the agent's Markdown/frontmatter failed to load at startup so it was never registered; a session reloaded settings with a different agents directory; the model hallucinated or partially-typed a name.

Common situations: agents directory path misconfigured or empty at startup; a typo in the agent's frontmatter name vs. what the model uses; an agent file excluded by a filter; dynamic registration that did not complete before the tool call.

Related errors

• Agent ' ' not found.
• Agent card is missing.
• Agent with name ' ' is already loaded.
• Attempted to save credentials without an access token.
• Cannot resume from eventId

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/912c765c3b90a4f4. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/src/agents/agent-tool.ts:90

        required: ['agent_name', 'prompt'],
      },
      messageBus,
      /* isOutputMarkdown */ true,
      /* canUpdateOutput */ true,
    );
  }

  protected createInvocation(
    params: { agent_name: string; prompt: string },
    messageBus: MessageBus,
    _toolName?: string,
    _toolDisplayName?: string,
  ): ToolInvocation<{ agent_name: string; prompt: string }, ToolResult> {
    const registry = this.context.config.getAgentRegistry();
    const definition = registry.getDefinition(params.agent_name);

    if (!definition) {
      throw new Error(`Subagent '${params.agent_name}' not found.`);
    }

    // Smart Parameter Mapping
    const mappedInputs = this.mapParams(
      params.prompt,
      definition.inputConfig.inputSchema,
    );

    return new DelegateInvocation(
      params,
      mappedInputs,
      messageBus,
      definition,
      this.context,
      _toolName,
      _toolDisplayName,
      this.onAgentEvent,
    );

View on GitHub (pinned to 5024443c72)