{"record":{"id":"912c765c3b90a4f4","repo":"google-gemini/gemini-cli","slug":"subagent-params-agent-name-not-found","errorCode":null,"errorMessage":"Subagent '${params.agent_name}' not found.","messagePattern":"Subagent '(.+?)' not found\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/agent-tool.ts","lineNumber":90,"sourceCode":"        required: ['agent_name', 'prompt'],\n      },\n      messageBus,\n      /* isOutputMarkdown */ true,\n      /* canUpdateOutput */ true,\n    );\n  }\n\n  protected createInvocation(\n    params: { agent_name: string; prompt: string },\n    messageBus: MessageBus,\n    _toolName?: string,\n    _toolDisplayName?: string,\n  ): ToolInvocation<{ agent_name: string; prompt: string }, ToolResult> {\n    const registry = this.context.config.getAgentRegistry();\n    const definition = registry.getDefinition(params.agent_name);\n\n    if (!definition) {\n      throw new Error(`Subagent '${params.agent_name}' not found.`);\n    }\n\n    // Smart Parameter Mapping\n    const mappedInputs = this.mapParams(\n      params.prompt,\n      definition.inputConfig.inputSchema,\n    );\n\n    return new DelegateInvocation(\n      params,\n      mappedInputs,\n      messageBus,\n      definition,\n      this.context,\n      _toolName,\n      _toolDisplayName,\n      this.onAgentEvent,\n    );","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/agent-tool.ts#L72-L108","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the agent is listed by the registry (inspect Config.getAgentRegistry().getDefinition(name)).","Check agent load logs / startup errors for AgentLoadError on that file.","Correct the agent_name in the tool call to match the frontmatter 'name' field exactly (case-sensitive).","Ensure the agents directory is configured and the target .md file passes validation."],"exampleFix":"// before - model calls agent tool with a misspelled name\n{ agent_name: 'resercher', prompt: '...' }\n\n// after\n{ agent_name: 'researcher', prompt: '...' }","handlingStrategy":"validation","validationCode":"const registry = config.getAgentRegistry();\nif (!registry.getDefinition(requestedName)) {\n  const known = registry.listDefinitions().map((d) => d.name);\n  throw new Error(`Unknown subagent '${requestedName}'. Known: ${known.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Before emitting an agent tool call, validate the name against the registry.","Log registry contents at startup so missing agents are obvious.","Treat agent load failures at startup as fatal so the registry is complete."],"tags":["subagent","agent-registry","tool","validation"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}