What causes "agentUrl is not a valid URL: {rawUrl} — {message}" in conductor-oss/conductor?

Verify the agentUrl is a well-formed http(s) URL, e.g. 'https://agent.example.com'

conductor-oss/conductor · error · NonRetryableException

agentUrl is not a valid URL: {rawUrl} — {message}

Error message

agentUrl is not a valid URL: {rawUrl} — {message}

What it means

Thrown by A2AService.validateAgentUrl() as a catch-all for any exception during URL parsing or DNS resolution that is not already a NonRetryableException. This covers MalformedURLException, UnknownHostException, and other resolution failures. It is a NonRetryableException (FAILED_WITH_TERMINAL_ERROR, no retry).

Source

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

                }
                if (addr.isLoopbackAddress()
                        || addr.isSiteLocalAddress()
                        || addr.isLinkLocalAddress()
                        || addr.isAnyLocalAddress()
                        || isUniqueLocalIpv6(addr)) {
                    A2AMetrics.ssrfBlocked();
                    throw new NonRetryableException(
                            "agentUrl resolves to a private/reserved address — SSRF blocked: "
                                    + addr.getHostAddress()
                                    + " (set "
                                    + ALLOW_PRIVATE_NETWORK_PROPERTY
                                    + "=true to allow private-network agents)");
                }
            }
        } catch (NonRetryableException e) {
            throw e;
        } catch (Exception e) {
            throw new NonRetryableException(
                    "agentUrl is not a valid URL: " + rawUrl + " — " + e.getMessage(), e);
        }
    }

    /**
     * Cloud metadata endpoints, blocked even when private networks are allowed: IPv4 link-local
     * 169.254.0.0/16 (AWS IMDS 169.254.169.254, ECS 169.254.170.2) and the IPv6 metadata addresses
     * (AWS {@code fd00:ec2::254}, link-local {@code fe80::a9fe:a9fe}).
     */
    private static boolean isMetadataAddress(InetAddress addr) {
        byte[] b = addr.getAddress();
        if (b.length == 4) {
            return (b[0] & 0xFF) == 169 && (b[1] & 0xFF) == 254;
        }
        return METADATA_IPV6.contains(addr);
    }

    /**

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Verify the agentUrl is a well-formed http(s) URL, e.g. 'https://agent.example.com'
Check DNS resolution for the hostname (e.g. nslookup or dig)
Correct any syntax issues in the URL string
If using an internal hostname, ensure it is resolvable from the Conductor server's network context

Example fix

// before
{"agentUrl": "my-agent-host"}
// after
{"agentUrl": "https://my-agent-host.internal.example.com"}

Defensive patterns

Strategy: validation

Validate before calling

// Validate URL format and DNS before the A2A call
try {
    URL url = new URL(agentUrl.trim());
    InetAddress.getAllByName(url.getHost()); // pre-check DNS
} catch (MalformedURLException e) {
    throw new IllegalArgumentException("agentUrl is not a valid URL: " + agentUrl, e);
} catch (UnknownHostException e) {
    throw new IllegalArgumentException("agentUrl hostname cannot be resolved: " + agentUrl, e);
}

Type guard

public boolean isResolvableUrl(String url) {
    if (url == null || url.isBlank()) return false;
    try {
        URL u = new URL(url.trim());
        InetAddress.getAllByName(u.getHost());
        return true;
    } catch (Exception e) {
        return false;
    }
}

Try / catch

try {
    a2aService.validateAgentUrl(agentUrl);
} catch (NonRetryableException e) {
    if (e.getMessage().contains("not a valid URL")) {
        log.error("agentUrl is malformed or unresolvable: {}", e.getMessage());
    }
    throw e;
}

Prevention

Validate URL syntax before passing to A2A operations
Ensure DNS is properly configured for internal hostnames in the Conductor deployment
Use fully qualified domain names to avoid DNS resolution ambiguity
Test URL resolution from the Conductor server's network context

When it happens

Trigger: new URL(rawUrl) throws MalformedURLException (e.g. missing protocol, invalid characters), or InetAddress.getAllByName(host) throws UnknownHostException (DNS resolution failure), or other network-related exceptions during host resolution.

Common situations: The agentUrl has invalid syntax (e.g. 'my-agent' without a protocol, spaces, special characters). The hostname does not exist in DNS. The DNS server is unreachable from the Conductor instance. The URL contains characters that break java.net.URL parsing.

Related errors

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