google-gemini/gemini-cli · error · Error

Remote agent '${def.name}' has neither agentCardUrl nor agen

Error message

Remote agent '${def.name}' has neither agentCardUrl nor agentCardJson

What it means

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.

Source

Thrown at packages/core/src/agents/types.ts:166

  name: string;
  agentCardUrl?: string;
  agentCardJson?: string;
}

/**
 * Derives the AgentCardLoadOptions from a RemoteAgentDefinition.
 * Throws if neither agentCardUrl nor agentCardJson is present.
 */
export function getAgentCardLoadOptions(
  def: RemoteAgentRef,
): AgentCardLoadOptions {
  if (def.agentCardJson) {
    return { type: 'json', json: def.agentCardJson };
  }
  if (def.agentCardUrl) {
    return { type: 'url', url: def.agentCardUrl };
  }
  throw new Error(
    `Remote agent '${def.name}' has neither agentCardUrl nor agentCardJson`,
  );
}

/**
 * Extracts a target URL for auth providers from a RemoteAgentDefinition.
 * For URL-based agents, returns the agentCardUrl.
 * For JSON-based agents, attempts to parse the URL from the inline card JSON.
 * Returns undefined if no URL can be determined.
 */
export function getRemoteAgentTargetUrl(
  def: RemoteAgentRef,
): string | undefined {
  if (def.agentCardUrl) {
    return def.agentCardUrl;
  }
  if (def.agentCardJson) {
    try {

View on GitHub (pinned to 5024443c72)

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).

Example fix

// before — neither field set
const def: RemoteAgentDefinition = {
  name: 'my-remote-agent',
  description: '...',
  kind: 'remote',
  inputConfig: { /* ... */ },
};

// after — provide an agent card URL
const def: RemoteAgentDefinition = {
  name: 'my-remote-agent',
  description: '...',
  kind: 'remote',
  agentCardUrl: 'https://my-agent.example.com/.well-known/agent.json',
  inputConfig: { /* ... */ },
};

Defensive patterns

Strategy: validation

Validate before calling

// Validate remote agent definition has a resolvable card before registration
function validateRemoteAgentDef(def: RemoteAgentDefinition): void {
  if (!def.agentCardUrl && !def.agentCardJson) {
    throw new Error(
      `Remote agent '${def.name}' must have agentCardUrl or agentCardJson set.`
    );
  }
}

// Call during registry load
for (const def of remoteDefs) validateRemoteAgentDef(def);

Type guard

function hasAgentCardSource(
  def: RemoteAgentDefinition
): def is RemoteAgentDefinition & { agentCardUrl: string } | RemoteAgentDefinition & { agentCardJson: string } {
  return Boolean(def.agentCardUrl) || Boolean(def.agentCardJson);
}

Try / catch

try {
  const loadOpts = getAgentCardLoadOptions(def);
} catch (e) {
  if (e instanceof Error && e.message.includes('neither agentCardUrl nor agentCardJson')) {
    // Skip or disable this agent entry, warn the user
    console.warn(`Skipping agent '${def.name}': no agent card source configured.`);
    continue;
  }
  throw e;
}

Prevention

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).

When it happens

Trigger: 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().

Common situations: 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.

Related errors

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