alibaba/nacos · error · IllegalStateException

HTTP + result.getStatusCode() + when fetching + url

Error message

HTTP  + result.getStatusCode() +  when fetching  + url

What it means

Thrown by SkillWellKnownImportService.fetchBytes() as an IllegalStateException when a raw byte fetch (used for index documents or remote references) returns a non-success HTTP status. The message includes the status code and the requested URL.

Source

Thrown at plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/skill/SkillWellKnownImportService.java:531

    private String trimTrailingSlash(String value) throws NacosException {
        if (StringUtils.isBlank(value)) {
            throw invalid("Skill well-known import source endpoint must not be empty.");
        }
        return trimTrailingSlashUnchecked(value);
    }
    
    private String trimTrailingSlashUnchecked(String value) {
        String result = value.trim();
        while (result.endsWith("/")) {
            result = result.substring(0, result.length() - 1);
        }
        return result;
    }
    
    private byte[] fetchBytes(String url) throws Exception {
        ImportHttpResponse result = fetchUrl(url);
        if (!result.isSuccess()) {
            throw new IllegalStateException(
                "HTTP " + result.getStatusCode() + " when fetching " + url);
        }
        return result.getBody();
    }
    
    private ImportHttpResponse fetchUrl(String url) throws Exception {
        return httpClient.get(url, DEFAULT_READ_TIMEOUT_SECONDS, "*/*");
    }
    
    private WellKnownIndexVersion resolveVersion(WellKnownSkillsIndex index)
        throws NacosException {
        String schema = index.getSchema();
        if (StringUtils.isBlank(schema) || StringUtils.equals(schema, SCHEMA_0_1)
            || schema.contains("/0.1.0/")) {
            return WellKnownIndexVersion.V0_1_0;
        }
        if (StringUtils.equals(schema, SCHEMA_0_2) || schema.contains("/0.2.0/")) {
            return WellKnownIndexVersion.V0_2_0;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Open the URL shown in the message directly (curl -I) to see the actual response.
2. Correct the source URL / allow-list the host in network egress rules.
3. Retry transient failures; for persistent errors, point the import at a different/cached source.

Example fix

// before
String url = "https://example.invalid/.well-known/skills.json";

// after
String url = "https://example.com/.well-known/skills.json";

ImportHttpResponse probe = fetchUrl(url);
if (!probe.isSuccess()) {
    throw new IllegalStateException("Source unreachable: HTTP " + probe.getStatusCode() + " @ " + url);
}

try {
    return fetchBytes(url);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("HTTP 5") && attempt < maxRetries) { /* retry */ }
    throw e;
}

When it happens

Trigger: fetchUrl(url) returns a response where result.isSuccess() is false; the throw fires before result.getBody() is returned. Used for resolving well-known index JSON or supplementary resources during skill import.

Common situations: The well-known index URL is unreachable (404/5xx); the skill source host is down; a relative reference resolved to an invalid absolute URL; network egress restrictions blocking the host.

Related errors

• HTTP + result.getStatusCode() + when fetching + result.ge
• HTTP + response.getStatusCode() + when fetching + respons
• HTTP + code + when fetching + pageUrl
• HTTP ${code} when fetching ${pageUrl}
• 10000

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