alibaba/nacos · error · IllegalArgumentException

Invalid {fieldName}: {value}

Error message

Invalid {fieldName}: {value}

What it means

Thrown by validateAbsoluteUri when a required absolute URI field is empty or longer than MAX_URI_LENGTH (2048 code points). This is the first of three guards inside validateAbsoluteUri; it checks the raw string before attempting URI parsing, so it catches empty strings and over-long values cheaply. The fieldName identifies which Agent field failed (iconUrl or provider.url).

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:625

            expected = RuntimeEndpointState.AVAILABLE;
        }
        if (item.getState() != expected) {
            throw new IllegalArgumentException(
                "Runtime Endpoint state must be " + expected.name());
        }
    }
    
    private static void validateEndpoint(Endpoint endpoint) {
        requireNonNull(endpoint, "Endpoint");
        EndpointCanonicalizer.canonicalize(endpoint);
        if (endpoint.getHealthy() != null) {
            throw new IllegalArgumentException("Management or declared Endpoint forbids healthy");
        }
    }
    
    private static void validateAbsoluteUri(String value, String fieldName) {
        if (value.isEmpty() || codePointLength(value) > MAX_URI_LENGTH) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value);
        }
        try {
            URI uri = new URI(value);
            if (!uri.isAbsolute()) {
                throw new IllegalArgumentException("Invalid " + fieldName + ": " + value);
            }
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value, e);
        }
    }
    
    private static void validateRequiredLength(String value, int maximum, String fieldName) {
        if (value == null || value.isEmpty() || codePointLength(value) > maximum) {
            throw new IllegalArgumentException("Invalid " + fieldName + ": " + value);
        }
    }
    
    private static void validateOptionalLength(String value, int maximum, String fieldName) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. For optional iconUrl/provider.url, omit the field (send null) rather than an empty string.
2. Shorten the URI to <= 2048 code points; for icons, host the image and use a short https URL instead of an inline data: URI.
3. If the URL is genuinely long (signed/CDN), store a stable short redirector URL instead.
4. Trim whitespace and confirm codePointCount (not byte length) is within 2048.

Example fix

// before
agent.setIconUrl(""); // empty -> rejected
provider.setUrl(longSignedDataUri); // > 2048 code points -> rejected
// after
agent.setIconUrl(null); // omit when unused
provider.setUrl("https://cdn.example.com/icon.png");

static void checkAbsUri(String v, String field) {
    if (v != null && (v.isEmpty() || v.codePointCount(0, v.length()) > 2048)) {
        throw new IllegalArgumentException("Invalid " + field + ": " + v);
    }
}
checkAbsUri(agent.getIconUrl(), "iconUrl");
if (agent.getProvider() != null) checkAbsUri(agent.getProvider().getUrl(), "provider.url");

static boolean uriLengthOk(String v) {
    return v == null || (!v.isEmpty() && v.codePointCount(0, v.length()) <= 2048);
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid iconUrl") || e.getMessage().startsWith("Invalid provider.url")) {
        // shorten or null-out the offending URI
    } else throw e;
}

When it happens

Trigger: An Agent publish/update where iconUrl (Agent.getIconUrl()) or provider.url (AgentProvider.getUrl()) is an empty string or a string whose codePointCount exceeds 2048. Reached via validateAgentFields -> validateAbsoluteUri. Note iconUrl is optional overall but, when present and non-null, is validated; an empty (not null) iconUrl fails here.

Common situations: Submitting iconUrl as "" instead of null/omitted; pasting a data: URI or a very long signed URL for an icon; a provider URL with many query parameters exceeding the limit; truncation bugs that produce empty strings.

Related errors

• 10000
• Invalid Agent Version storage {field}
• Invalid {fieldName}: exceeds {maximum}
• Invalid agentName: {agentName}
• 20002

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