alibaba/nacos · warning · Error

AgentCard interface must be a JSON object

Error message

AgentCard interface must be a JSON object

What it means

Thrown by normalizeA2aInterface() in agent-console-model when an element of supportedInterfaces (or additionalInterfaces) is not a JSON object. Each A2A interface entry must be an object containing url, protocolBinding/transport, and protocolVersion.

Source

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

}

function sourceMode(order) {
  const key = (order || []).join(',');
  switch (key) {
    case 'RUNTIME,DECLARED':
      return 'runtime-declared';
    case 'DECLARED':
      return 'declared-only';
    case 'RUNTIME':
      return 'runtime-only';
    default:
      return 'declared-runtime';
  }
}

function normalizeA2aInterface(value, fallbackTransport, fallbackVersion) {
  if (!isObject(value)) {
    throw new Error('AgentCard interface must be a JSON object');
  }
  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'));

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Make every entry in supportedInterfaces a JSON object with at least a url field.
2. Use the default card shape as a template: {"url":"...","protocolBinding":"HTTP+JSON","protocolVersion":"0.3"}.
3. Remove null or primitive entries from the array.

Example fix

// before
"supportedInterfaces": ["https://agent.example.com/a2a"]

// after
"supportedInterfaces": [{"url":"https://agent.example.com/a2a","protocolBinding":"HTTP+JSON","protocolVersion":"0.3"}]

function interfacesAreObjects(arr) {
  return Array.isArray(arr) && arr.every(i => i !== null && !Array.isArray(i) && typeof i === 'object');
}

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

try {
  supportedInterfaces.map(item => normalizeA2aInterface(item, preferredTransport, topProtocolVersion));
} catch (e) {
  Message.error(e.message); // 'AgentCard interface must be a JSON object'
  return;
}

When it happens

Trigger: Submitting an AgentCard whose supportedInterfaces array contains a primitive, null, or a string instead of an object, e.g. "supportedInterfaces":["https://x"] or "supportedInterfaces":[42].

Common situations: Hand-writing an AgentCard JSON with a simplified interface list, or misinterpreting the schema where a bare URL was expected.

Related errors

• agentCard must be a JSON object
• 20002
• PARAMETER_VALIDATE_ERROR
• Labels must be a JSON object
• The latest label is managed by the server

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