alibaba/nacos · warning · Error

agentCard must be a JSON object

Error message

agentCard must be a JSON object

What it means

Thrown by normalizeA2aAgentCard() in agent-console-model when the parsed AgentCard text is valid JSON but is not a plain object (e.g., it is an array or a primitive). The A2A AgentCard must be a single JSON object. This is distinct from a JSON syntax error (987) and from the projection-time check (999).

Source

Thrown at console-ui/src/pages/AI/agent-console-model.js:165

  const url = required(optionalString(value.url) || '', 'AgentCard interface url');
  const protocolBinding = validateTransport(
    optionalString(value.protocolBinding) ||
      optionalString(value.transport) ||
      fallbackTransport ||
      ''
  );
  endpointKey(url, protocolBinding);
  const protocolVersion = required(
    optionalString(value.protocolVersion) || fallbackVersion || '',
    'AgentCard interface protocolVersion'
  );
  return { ...value, url, transport: protocolBinding, protocolBinding, protocolVersion };
}

function normalizeA2aAgentCard(agentName, version, text) {
  const parsed = parseAgentCardJson(required(text, 'agentCard'));
  if (!isObject(parsed)) {
    throw new Error('agentCard must be a JSON object');
  }
  const card = { ...parsed, name: agentName, version };
  const topProtocolVersion = optionalString(card.protocolVersion);
  const preferredTransport = optionalString(card.preferredTransport);
  let interfaces;
  if (Array.isArray(card.supportedInterfaces) && card.supportedInterfaces.length > 0) {
    interfaces = card.supportedInterfaces.map(item => {
      return normalizeA2aInterface(item, preferredTransport, topProtocolVersion);
    });
  } else {
    const preferred = normalizeA2aInterface(
      {
        url: card.url,
        protocolBinding: preferredTransport,
        protocolVersion: topProtocolVersion,
      },
      undefined,
      undefined

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure the agentCard text is a single JSON object delimited by { }.
2. Start from DEFAULT_AGENT_CARD as a template.
3. Remove outer array brackets or quotes around the object.

Example fix

// before
[{"name":"x","version":"1"}]

// after
{"name":"x","version":"1"}

function parsedCardIsObject(text) {
  let p;
  try { p = parseAgentCardJson(text); } catch { return false; }
  return p !== null && !Array.isArray(p) && typeof p === 'object';
}

function isPlainObject(v) {
  return v !== null && !Array.isArray(v) && typeof v === 'object';
}

try {
  normalizeA2aAgentCard(agentName, version, text);
} catch (e) {
  Message.error(e.message); // 'agentCard must be a JSON object'
  return;
}

When it happens

Trigger: Pasting a JSON array or a bare string/number as the agentCard value during structured A2A protocol editing, e.g. agentCard = '[]' or agentCard = '"hello"'.

Common situations: User wraps the card in an array, or pastes only a URL string where the full card object is expected.

Related errors

• AgentCard interface must be a JSON object
• INVALID_PARAM
• 20002
• PARAMETER_VALIDATE_ERROR
• Labels must be a JSON object

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/184111bd12f7516d. Report an issue: GitHub.