alibaba/nacos · error · Error

nativeDescriptor must not be JSON null

Error message

nativeDescriptor must not be JSON null

What it means

Thrown when the custom nativeDescriptor JSON parses successfully but its value is exactly JSON null. A non-null object/array/string is accepted, but null is rejected because a null descriptor carries no protocol information and would produce an empty endpoint entry.

Source

Thrown at console-ui-next/src/pages/newAgent/agent-console-model.ts:324

  editor: StructuredProtocolEditorValues,
): AgentCallInterface {
  if (editor.protocolEditorKind === 'a2a') {
    const normalized = normalizeA2aAgentCard(agentName, version, editor.agentCard);
    return {
      protocol: 'a2a',
      protocolVersion: String(normalized.card.protocolVersion),
      descriptorMediaType: 'application/json',
      nativeDescriptor: normalized.card,
      endpointSourceOrder: ['DECLARED', 'RUNTIME'],
      declaredEndpoints: normalized.declaredEndpoints,
    };
  }
  const nativeDescriptor = parseJson(
    required(editor.customNativeDescriptor, 'nativeDescriptor'),
    'nativeDescriptor',
  );
  if (nativeDescriptor === null) {
    throw new Error('nativeDescriptor must not be JSON null');
  }
  const seen = new Set<string>();
  const declaredEndpoints = editor.declaredEndpoints.flatMap((endpoint) => {
    if (!endpoint.uri.trim() && !endpoint.transport.trim()) {
      return [];
    }
    const uri = required(endpoint.uri, 'Endpoint uri');
    const transport = validateTransport(endpoint.transport);
    const key = endpointKey(uri, transport);
    if (seen.has(key)) {
      return [];
    }
    seen.add(key);
    return [{ uri, transport }];
  });
  return {
    protocol: required(editor.customProtocol, 'protocol'),
    protocolVersion: editor.customProtocolVersion.trim() || undefined,

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide an actual descriptor object, e.g. {} or {"openapi":"3.0.0"}, not null.
2. If the descriptor is optional, leave the field empty rather than typing null.
3. Reject literal null client-side before submit.

Example fix

// before
nativeDescriptor = 'null'

// after
nativeDescriptor = '{"openapi":"3.0.0","paths":{}}'

function checkDescriptor(parsed) { if (parsed === null) throw new Error('nativeDescriptor must not be null'); }

function isNonNullJson(v: unknown): boolean { return v !== null; }

try { parseJson(descriptor, 'nativeDescriptor'); } catch (e) {
  if (/must not be JSON null/.test(e.message)) { toast.error('Provide an actual descriptor object'); }
}

When it happens

Trigger: User enters the literal text 'null' in the nativeDescriptor field, or a JSON whose intended descriptor field resolved to null.

Common situations: Default placeholder is 'null'. User clears the field and a default null is inserted. Misunderstanding that null means 'no descriptor'.

Related errors

• Labels must be a JSON object
• ${name} must be valid JSON
• ${name} must be a JSON object
• callInterfaces must be a non-empty JSON array
• agent.labelsObjectRequired

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