{"record":{"id":"059b88362f1bc74c","repo":"slopus/happy","slug":"unknown-agent-id-available-agents-availabl","errorCode":null,"errorMessage":"Unknown agent: ${id}. Available agents: ${available}","messagePattern":"Unknown agent: (.+?)\\. Available agents: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/happy-cli/src/agent/core/AgentRegistry.ts","lineNumber":81,"sourceCode":"   * @returns Array of registered agent IDs\n   */\n  list(): AgentId[] {\n    return Array.from(this.factories.keys());\n  }\n\n  /**\n   * Create an agent backend instance.\n   * \n   * @param id - The agent identifier\n   * @param opts - Options for creating the backend\n   * @returns The created agent backend\n   * @throws Error if the agent type is not registered\n   */\n  create(id: AgentId, opts: AgentFactoryOptions): AgentBackend {\n    const factory = this.factories.get(id);\n    if (!factory) {\n      const available = this.list().join(', ') || 'none';\n      throw new Error(`Unknown agent: ${id}. Available agents: ${available}`);\n    }\n    return factory(opts);\n  }\n}\n\n/** Global agent registry instance */\nexport const agentRegistry = new AgentRegistry();\n\n","sourceCodeStart":63,"sourceCodeEnd":90,"githubUrl":"https://github.com/slopus/happy/blob/b824cd0a4681d41af631a8e422a813873e4455b0/packages/happy-cli/src/agent/core/AgentRegistry.ts#L63-L90","documentation":"AgentRegistry.create looks up a factory by agent id in its factories map. An unregistered id means the requested agent type was never registered (or the id is misspelled), so it throws listing all available agent ids. This is the guard against instantiating unknown agent backends.","triggerScenarios":"Passing an AgentId not passed to registry.register() in this process; a typo or casing mismatch in the id; calling create before the module that registers the agent was imported; a version change that renamed the agent id.","commonSituations":"Config file referencing an agent name removed/renamed in a CLI upgrade; plugin/module import order leaving the registry empty; using `acp` style inline commands where only a generic factory is expected but wasn't registered.","solutions":["Use one of the ids listed in the error's 'Available agents' output.","Ensure the module registering the agent factory is imported before create() is called.","Fix the id spelling/casing to match the registered AgentId.","If the agent was removed in an upgrade, migrate your config to the new id."],"exampleFix":"// before\nregistry.create('claudeCode', opts); // typo, not registered\n// after\nregistry.create('claude-code', opts);","handlingStrategy":"validation","validationCode":"const available = agentRegistry.list();\nif (!available.includes(agentId)) {\n  throw new Error(`Agent '${agentId}' not registered. Available: ${available.join(', ')}`);\n}\nconst agent = agentRegistry.create(agentId, opts);","typeGuard":"function isRegisteredAgent(id: string, registry: AgentRegistry): id is AgentId {\n  return registry.list().includes(id as AgentId);\n}","tryCatchPattern":"try {\n  return agentRegistry.create(id, opts);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unknown agent:')) {\n    console.error(`${err.message}\\nCheck your config agent name and that the agent module is imported.`);\n  } else throw err;\n}","preventionTips":["Import the module that registers each agent factory before create() runs.","Keep agent ids centralized in a typed constant/union to prevent typos.","When upgrading happy, diff agent ids against your config's agent names.","Log registry.list() at startup when debugging unknown-agent errors."],"tags":["registry","unknown-agent","configuration","typescript"],"backgroundTag":"unknown-identifier","analyzedSha":"b824cd0a4681d41af631a8e422a813873e4455b0","analyzedAt":"2026-08-31T23:12:36.205Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}