conductor-oss/conductor · error · NonRetryableException

Agent Card resolved from %s does not advertise a JSON-RPC 'u

Error message

Agent Card resolved from %s does not advertise a JSON-RPC 'url'

What it means

Thrown by A2AWorkers.resolveRemoteEndpoint when the configured agentUrl points at an Agent Card (path ends in '.json'), the card is successfully fetched via a2aService.getAgentCard, but card.getUrl() is null or blank. The A2A discovery document is required to advertise its JSON-RPC endpoint in a top-level 'url' field; without it Conductor cannot know where to POST JSON-RPC calls. It is a NonRetryableException, so the workflow task fails terminally rather than retrying.

Source

Thrown at ai/src/main/java/org/conductoross/conductor/ai/tasks/worker/A2AWorkers.java:365

     */
    private String resolveRemoteEndpoint(
            Task task, String configuredUrl, Map<String, String> headers) {
        String configured = StringUtils.trimToNull(configuredUrl);
        if (configured == null) {
            throw new NonRetryableException("agentUrl must not be blank");
        }

        String snapshottedEndpoint = endpointFromSnapshot(task);
        if (snapshottedEndpoint != null) {
            return snapshottedEndpoint;
        }

        String pathWithoutQuery = StringUtils.substringBefore(configured, "?");
        if (StringUtils.endsWithIgnoreCase(pathWithoutQuery, ".json")) {
            AgentCard card = a2aService.getAgentCard(configured, headers);
            String discoveredEndpoint = card == null ? null : StringUtils.trimToNull(card.getUrl());
            if (discoveredEndpoint == null) {
                throw new NonRetryableException(
                        "Agent Card resolved from "
                                + configured
                                + " does not advertise a JSON-RPC 'url'");
            }
            return discoveredEndpoint;
        }
        return configured;
    }

    private String endpointFromSnapshot(Task task) {
        if (task == null
                || task.getWorkflowTask() == null
                || task.getWorkflowTask().getMetadata() == null) {
            return null;
        }
        JsonNode agent =
                objectMapper.valueToTree(task.getWorkflowTask().getMetadata()).path("agent");
        if (!A2AService.isA2aAgentType(agent.path("agentType").asText())) {

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Open the Agent Card JSON at your configured agentUrl and confirm it has a top-level "url" field pointing at the JSON-RPC endpoint.
2. If the card genuinely has no url, point agentUrl directly at the JSON-RPC endpoint URL instead of the .json card.
3. Add/repair the 'url' field in the served Agent Card document so it advertises the JSON-RPC base URL.
4. Verify a2aService.getAgentCard reaches the real card (correct headers, no auth redirect to a login HTML page).

Example fix

// before
{ "agentUrl": "https://agent.example.com/.well-known/agent.json" }
// card missing url -> set the endpoint directly, or fix the card:
// after (option A: direct endpoint)
{ "agentUrl": "https://agent.example.com/a2a/jsonrpc" }
// after (option B: fix the served card)
{ "name": "agent", "url": "https://agent.example.com/a2a/jsonrpc", "version": "1.0" }

// Before setting agentUrl to a .json card, fetch and check the url field
AgentCard card = a2aService.getAgentCard(candidateUrl, headers);
if (card == null || StringUtils.isBlank(card.getUrl())) {
    // point agentUrl at the JSON-RPC endpoint directly instead of the card
    request.setAgentUrl(knownJsonRpcEndpoint);
} else {
    request.setAgentUrl(candidateUrl);
}

// resolveRemoteEndpoint already wraps NonRetryableException into a terminal task failure;
// catch at the workflow layer to mark the task and surface the discovery URL.
try {
    String ep = resolveRemoteEndpoint(task, url, headers);
} catch (NonRetryableException e) {
    // log configured card URL, fix the card or switch to direct endpoint
}

When it happens

Trigger: Setting agentUrl to a *.json Agent Card URL whose document has no 'url' key, or whose 'url' value is empty/whitespace. Also triggered when endpointFromSnapshot returns null (no task metadata snapshot) and the live card lacks the url field.

Common situations: Hosting an Agent Card JSON at a website URL but forgetting to include the 'url' field; pointing at a partial/mock card; card served by an older/non-compliant A2A agent that omits the JSON-RPC url; SSRF or fetch returning a different document (e.g. an HTML error page parsed as null card).

Related errors

• GET_AGENT_CARD requires 'agentUrl'
• AGENT requires one of: message, parts, text, or prompt
• Unsupported agentType '<agentType>' (only 'a2a' is supported
• agentUrl must not be blank
• agentUrl must use http or https, got: {scheme}

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/5b5fa4c9764b065f. Report an issue: GitHub.