What causes "A2A call '{method}' to {endpoint} failed: {message}" in conductor-oss/conductor?

Check network connectivity and DNS resolution for the agent endpoint

conductor-oss/conductor · error · A2AException

A2A call '{method}' to {endpoint} failed: {message}

Error message

A2A call '{method}' to {endpoint} failed: {message}

What it means

Thrown by A2AService.jsonRpc() as a catch-all for any unexpected exception during a JSON-RPC call that is not already an A2AException or NonRetryableException. Covers IO errors, timeouts, SSL issues, and JSON parsing failures. It is a retryable A2AException so the Conductor task will be retried.

Source

Thrown at ai/src/main/java/org/conductoross/conductor/ai/a2a/A2AService.java:411

                JsonNode json = parseBody(response, body);
                if (json.has("error") && !json.get("error").isNull()) {
                    throw jsonRpcError(endpoint, method, json.get("error"));
                }
                if (!json.has("result")) {
                    throw new A2AException(
                            "Invalid JSON-RPC response from "
                                    + endpoint
                                    + " for '"
                                    + method
                                    + "': missing 'result' field");
                }
                return json.get("result");
            }
        } catch (A2AException | NonRetryableException e) {
            throw e;
        } catch (Exception e) {
            // IO/timeout/parse errors are transient — let the task retry.
            throw new A2AException(
                    "A2A call '" + method + "' to " + endpoint + " failed: " + e.getMessage(), e);
        }
    }

    private JsonNode parseBody(Response response, String body) throws Exception {
        String contentType = response.header("Content-Type", "application/json");
        if (contentType != null && contentType.contains("text/event-stream")) {
            return parseSseResponse(body);
        }
        return objectMapper.readTree(body);
    }

    /**
     * Guards against SSRF: rejects URLs whose hostname resolves to an RFC-1918 address, loopback,
     * link-local (169.254.x.x — AWS/GCP/Azure metadata), or any non-http(s) scheme.
     *
     * <p>Note: DNS resolution is performed once here. A sufficiently hostile DNS server could
     * rebind the name to a private IP after this check (TOCTOU). For stronger protection, deploy

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Check network connectivity and DNS resolution for the agent endpoint
Verify the remote agent is running and accepting connections
Retry — this is a transient/retryable error
Check for firewall or network policy rules blocking outbound traffic to the agent
If the response body is invalid JSON, verify the agent endpoint returns proper JSON-RPC responses

Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight check: validate the URL and test basic connectivity
try {
    a2aService.validateAgentUrl(endpoint);
} catch (NonRetryableException e) {
    throw e; // non-retryable, fail immediately
}

Try / catch

try {
    A2ATask task = a2aService.getTask(endpoint, taskId, historyLength, headers);
} catch (A2AException e) {
    // Transient error — Conductor will retry the task
    log.warn("A2A JSON-RPC call failed (will retry): {}", e.getMessage());
    throw e;
} catch (NonRetryableException e) {
    // Terminal error — do not retry
    log.error("A2A JSON-RPC call failed (terminal): {}", e.getMessage());
    throw e;
}

Prevention

Monitor network connectivity between Conductor and remote agents
Set appropriate retry policies in the A2A worker task definitions
Implement health checks for remote agent endpoints
Use DNS caching and connection pooling to reduce transient failures

When it happens

Trigger: Any exception during the JSON-RPC POST — connection refused, read timeout, SSL handshake failure, JSON parse error on the response body, etc. — that isn't handled by the explicit A2AException/NonRetryableException re-throw or the HTTP error / JSON-RPC error branches.

Common situations: The remote agent is down or unreachable. DNS resolution fails for the agent hostname. The response body is not valid JSON. Connection pool exhaustion. Firewall rules block the outbound request.

Related errors

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