alibaba/nacos · error · IllegalArgumentException

{} must be an absolute URI

Error message

{} must be an absolute URI

What it means

validateOptionalAbsoluteUri() parses the URI and requires uri.isAbsolute() (a scheme is present). A relative URI such as '/icons/a.png' or 'icons/a.png' parses successfully but is not absolute, so it is rejected with '<fieldName> must be an absolute URI'.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java:234

            String current = versions.get(i).getVersion();
            if (AgentVersionComparator.compare(previous, current) <= 0) {
                throw new IllegalArgumentException(
                    "Agent Version catalog must use descending Version order");
            }
        }
    }
    
    private static void validateOptionalAbsoluteUri(String value, String fieldName) {
        if (value == null) {
            return;
        }
        if (value.isEmpty() || value.codePointCount(0, value.length()) > MAX_URI_LENGTH) {
            throw new IllegalArgumentException("Invalid " + fieldName);
        }
        try {
            URI uri = new URI(value);
            if (!uri.isAbsolute()) {
                throw new IllegalArgumentException(fieldName + " must be an absolute URI");
            }
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid " + fieldName, e);
        }
    }
    
    private static void validateOptionalCodePointLength(String value, int maxLength,
        String fieldName) {
        if (value != null && value.codePointCount(0, value.length()) > maxLength) {
            throw new IllegalArgumentException(fieldName + " exceeds " + maxLength
                + " Unicode code points");
        }
    }
    
    private static void validateRequiredCodePointLength(String value, int maxLength,
        String fieldName) {
        if (value == null || value.isEmpty()
            || value.codePointCount(0, value.length()) > maxLength) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide a fully-qualified absolute URI including a scheme, e.g. 'https://cdn.example.com/agent.png'.
2. For inline assets use a data: URI (which is absolute).
3. Avoid schemeless ('//host/...') and path-relative URIs for iconUrl/provider.url.

Example fix

// before
ext.setIconUrl("/assets/agent.png"); // relative -> not absolute

// after
ext.setIconUrl("https://cdn.example.com/assets/agent.png");

static boolean isAbsoluteUri(String v) {
    if (v == null || v.isEmpty()) return true; // optional
    try { return new java.net.URI(v).isAbsolute(); } catch (java.net.URISyntaxException e) { return false; }
}
if (!isAbsoluteUri(ext.getIconUrl())) throw new IllegalArgumentException("iconUrl must be absolute");

static boolean isAbsoluteUri(String v) {
    try { return v != null && !v.isEmpty() && new java.net.URI(v).isAbsolute(); }
    catch (java.net.URISyntaxException e) { return false; }
}

When it happens

Trigger: Setting iconUrl or provider.url to a path-only or schemeless reference (no 'http:'/'https:'/'data:' scheme) via the agent create/update API.

Common situations: Using a server-relative path intended for a web UI, or a protocol-relative URL ('//cdn/x.png') that java.net.URI treats as non-absolute.

Related errors

• Invalid {}
• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version agentName does not match request
• Agent Version status must be online

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