google-gemini/gemini-cli · error

Subagent '${params.agent_name}' 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.

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)

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

• Invalid taskId: ${taskId}
• Security violation: Null byte detected in path.
• Security violation: The path "${trimmedPath}" is outside the
• The path "${trimmedPath}" is not a directory.
• The path "${trimmedPath}" does not exist.

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