{"record":{"id":"ef71e9034dbb748b","repo":"google-gemini/gemini-cli","slug":"remote-agent-def-name-has-neither-agentcardur","errorCode":null,"errorMessage":"Remote agent '${def.name}' has neither agentCardUrl nor agentCardJson","messagePattern":"Remote agent '(.+?)' has neither agentCardUrl nor agentCardJson","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/types.ts","lineNumber":166,"sourceCode":"  name: string;\n  agentCardUrl?: string;\n  agentCardJson?: string;\n}\n\n/**\n * Derives the AgentCardLoadOptions from a RemoteAgentDefinition.\n * Throws if neither agentCardUrl nor agentCardJson is present.\n */\nexport function getAgentCardLoadOptions(\n  def: RemoteAgentRef,\n): AgentCardLoadOptions {\n  if (def.agentCardJson) {\n    return { type: 'json', json: def.agentCardJson };\n  }\n  if (def.agentCardUrl) {\n    return { type: 'url', url: def.agentCardUrl };\n  }\n  throw new Error(\n    `Remote agent '${def.name}' has neither agentCardUrl nor agentCardJson`,\n  );\n}\n\n/**\n * Extracts a target URL for auth providers from a RemoteAgentDefinition.\n * For URL-based agents, returns the agentCardUrl.\n * For JSON-based agents, attempts to parse the URL from the inline card JSON.\n * Returns undefined if no URL can be determined.\n */\nexport function getRemoteAgentTargetUrl(\n  def: RemoteAgentRef,\n): string | undefined {\n  if (def.agentCardUrl) {\n    return def.agentCardUrl;\n  }\n  if (def.agentCardJson) {\n    try {","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/types.ts#L148-L184","documentation":"Thrown by getAgentCardLoadOptions() when a RemoteAgentDefinition has neither agentCardUrl nor agentCardJson. This function derives the AgentCardLoadOptions discriminated union used by A2AClientManager.loadAgent() to fetch or parse the agent card. Every remote agent must be resolvable either via a URL endpoint or an inline JSON card; without either, the system has no way to discover the agent's capabilities.","triggerScenarios":"Calling getAgentCardLoadOptions(def) where def.agentCardJson is falsy AND def.agentCardUrl is falsy. This propagates through loadAgent() calls in both RemoteSubagentProtocol._runStream() and RemoteSessionInvocation.sessionKey().","commonSituations":"A remote agent definition in settings.json or an extension was declared with a name but missing both the url and inline card fields; the fields were typo'd (e.g., agentCardURL with wrong casing); a dynamically-built definition object omitted the card fields due to a construction bug; an agent definition was partially loaded from a malformed config file.","solutions":["Add either agentCardUrl (a resolvable HTTP endpoint) or agentCardJson (a stringified AgentCard) to the remote agent definition.","Validate definitions at registration time: check that every RemoteAgentDefinition has at least one of the two fields before accepting it into the registry.","If loading from a config file, add schema validation (Zod) that enforces one-of agentCardUrl/agentCardJson.","Check for field-name typos — the properties are case-sensitive (agentCardUrl, not agentCardURL)."],"exampleFix":"// before — neither field set\nconst def: RemoteAgentDefinition = {\n  name: 'my-remote-agent',\n  description: '...',\n  kind: 'remote',\n  inputConfig: { /* ... */ },\n};\n\n// after — provide an agent card URL\nconst def: RemoteAgentDefinition = {\n  name: 'my-remote-agent',\n  description: '...',\n  kind: 'remote',\n  agentCardUrl: 'https://my-agent.example.com/.well-known/agent.json',\n  inputConfig: { /* ... */ },\n};","handlingStrategy":"validation","validationCode":"// Validate remote agent definition has a resolvable card before registration\nfunction validateRemoteAgentDef(def: RemoteAgentDefinition): void {\n  if (!def.agentCardUrl && !def.agentCardJson) {\n    throw new Error(\n      `Remote agent '${def.name}' must have agentCardUrl or agentCardJson set.`\n    );\n  }\n}\n\n// Call during registry load\nfor (const def of remoteDefs) validateRemoteAgentDef(def);","typeGuard":"function hasAgentCardSource(\n  def: RemoteAgentDefinition\n): def is RemoteAgentDefinition & { agentCardUrl: string } | RemoteAgentDefinition & { agentCardJson: string } {\n  return Boolean(def.agentCardUrl) || Boolean(def.agentCardJson);\n}","tryCatchPattern":"try {\n  const loadOpts = getAgentCardLoadOptions(def);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('neither agentCardUrl nor agentCardJson')) {\n    // Skip or disable this agent entry, warn the user\n    console.warn(`Skipping agent '${def.name}': no agent card source configured.`);\n    continue;\n  }\n  throw e;\n}","preventionTips":["Add Zod schema validation for remote agent definitions enforcing one-of url/json.","Log a warning at startup for any agent definition missing both card fields.","Provide a config linter or CLI doctor command that checks agent definitions.","Use consistent property names — agentCardUrl (not agentCardURL)."],"tags":["a2a","remote-agents","agent-card","configuration"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}