google-gemini/gemini-cli · error

Failed to parse inline agent card JSON for agent '${name}':

Error message

Failed to parse inline agent card JSON for agent '${name}': ${msg}

What it means

Thrown when an inline agent card supplied via `{ type: 'json', json: '...' }` fails to parse. The manager wraps `JSON.parse` in a try/catch; any SyntaxError (or non-Error throw) is re-thrown with the agent name and the underlying parse message so the caller can see exactly why the JSON was rejected.

Source

Thrown at packages/core/src/agents/a2a-client-manager.ts:132

      // Retry with auth if we hit a 401/403
      if ((response.status === 401 || response.status === 403) && authFetch) {
        return authFetch(input, init);
      }

      return response;
    };

    const resolver = new DefaultAgentCardResolver({ fetchImpl: cardFetch });

    let rawCard: unknown;
    let urlIdentifier = 'inline JSON';

    if (options.type === 'json') {
      try {
        rawCard = JSON.parse(options.json);
      } catch (error) {
        const msg = error instanceof Error ? error.message : String(error);
        throw new Error(
          `Failed to parse inline agent card JSON for agent '${name}': ${msg}`,
        );
      }
    } else {
      urlIdentifier = options.url;
      rawCard = await resolver.resolve(options.url, '');
    }

    // TODO: Remove normalizeAgentCard once @a2a-js/sdk handles
    // proto field name aliases (supportedInterfaces → additionalInterfaces,
    // protocolBinding → transport).
    const agentCard = normalizeAgentCard(rawCard);

    const grpcUrl =
      agentCard.additionalInterfaces?.find((i) => i.transport === 'GRPC')
        ?.url ?? agentCard.url;

    const clientOptions = ClientFactoryOptions.createFrom(

View on GitHub (pinned to 5024443c72)

Solutions

1. Validate the JSON string with `JSON.parse` in isolation before passing it to loadAgent, and fix the syntax error reported.
2. Strip markdown code fences and surrounding whitespace/prose from the string.
3. Load the card from a URL (`options.type === 'url'`) instead of inline to let the resolver fetch a clean copy.
4. If the JSON is generated, run the generator's output through a JSON schema validator for AgentCard.

Example fix

// before
await manager.loadAgent('rev', { type: 'json', json: `{ name: 'rev' }` }); // unquoted keys

// after
await manager.loadAgent('rev', { type: 'json', json: JSON.stringify({ name: 'rev' }) });

function tryParseAgentCardJson(name: string, json: string): unknown {
  try {
    return JSON.parse(json);
  } catch (e) {
    throw new Error(
      `Invalid inline agent card JSON for '${name}': ${(e as Error).message}`,
    );
  }
}

const card = tryParseAgentCardJson('rev', options.json);
await manager.loadAgent('rev', { type: 'json', json: JSON.stringify(card) });

function isParsableJson(s: string): boolean {
  try { JSON.parse(s); return true; } catch { return false; }
}

try {
  await manager.loadAgent('rev', { type: 'json', json });
} catch (e) {
  if (e instanceof Error && e.message.includes('Failed to parse inline agent card JSON')) {
    // fall back to loading from URL, or prompt user for corrected JSON
  }
  throw e;
}

When it happens

Trigger: Passing `loadAgent` with `options.type === 'json'` and a `options.json` string that is not valid JSON: trailing commas, single quotes, unquoted keys, an unterminated string, or a value that is not an object. Also triggered when the inline string is empty or contains a markdown fence around the JSON.

Common situations: Hand-written JSON in a config file with a trailing comma; copy-pasting an AgentCard from docs that includes ` ```json ` fences; reading the JSON from a file but forgetting to strip a BOM or surrounding whitespace; a template literal that produced malformed output.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Agent card is missing.
• ${errorMessages.join('\n')}\nPlease fix the configuration fi
• Agent with name '${name}' is already loaded.
• Agent '${agentName}' not found.
• Remote agent '${def.name}' has neither agentCardUrl nor agen

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