alibaba/nacos · error · IllegalStateException

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

Error message

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

What it means

Thrown by SkillWellKnownImportService.fetchVersion020Artifact() as an IllegalStateException when fetching a Skill well-known 0.2.0 artifact (the downloadable skill payload referenced by an index entry) returns a non-success HTTP status. The message includes the status code and the resolved artifact 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:348

        ImportHttpResponse artifact = fetchVersion020Artifact(resolvedIndex, entry);
        if (TYPE_SKILL_MD.equals(type)) {
            return toSingleMarkdownSkillZip(entry.getName(), artifact.getBody());
        }
        if (TYPE_ARCHIVE.equals(type)) {
            return toSkillZipFromArchive(artifact);
        }
        throw invalid("Unsupported Skill well-known distribution type: " + entry.getType());
    }
    
    private ImportHttpResponse fetchVersion020Artifact(ResolvedWellKnownIndex resolvedIndex,
        WellKnownSkillEntry entry) throws Exception {
        if (StringUtils.isBlank(entry.getUrl())) {
            throw invalid("Skill well-known 0.2.0 entry url must not be empty.");
        }
        ImportHttpResponse result =
            fetchUrl(resolveArtifactUrl(resolvedIndex.getIndexUrl(), entry.getUrl()));
        if (!result.isSuccess()) {
            throw new IllegalStateException(
                "HTTP " + result.getStatusCode() + " when fetching " + result.getUrl());
        }
        checkDownloadedSize(result.getBody());
        verifySha256Digest(entry.getDigest(), result.getBody());
        return result;
    }
    
    private byte[] toSingleMarkdownSkillZip(String skillName, byte[] markdown) throws Exception {
        ByteArrayOutputStream output = new ByteArrayOutputStream();
        try (ZipOutputStream zip = new ZipOutputStream(output, StandardCharsets.UTF_8)) {
            zip.putNextEntry(new ZipEntry(skillName + "/" + MARKDOWN_FILE));
            zip.write(markdown);
            zip.closeEntry();
        }
        return output.toByteArray();
    }
    
    private byte[] toSkillZipFromArchive(ImportHttpResponse artifact) throws Exception {

View on GitHub (pinned to 9b989acdf1)

Solutions

Inspect the resolved artifact URL in the message and open it in a browser/curl to confirm.
Update the well-known index entry's url field to the correct artifact location.
Retry transient 5xx errors; for persistent 404, report the broken entry to the index maintainer.

Example fix

// before: index entry points to a stale URL
{"name":"my-skill","url":"/old/path/skill.md"}

// after: corrected artifact URL
{"name":"my-skill","url":"/skills/my-skill/skill.md"}

Defensive patterns

Strategy: retry

Validate before calling

// Probe the resolved artifact URL before the full import.
ImportHttpResponse probe = fetchUrl(resolveArtifactUrl(indexUrl, entry.getUrl()));
if (!probe.isSuccess()) {
    throw new IllegalStateException("Artifact unreachable: HTTP " + probe.getStatusCode());
}

Try / catch

try {
    return fetchVersion020Artifact(resolvedIndex, entry);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("HTTP 4")) {
        // permanent: report broken entry to index maintainer
    }
    throw e;
}

Prevention

Validate index entry URLs resolve before publishing the well-known index.
Keep artifact URLs stable; use redirects instead of breaking links.
Cache downloaded artifacts to survive transient upstream failures.

When it happens

Trigger: During a 0.2.0 skill import, fetchUrl(resolveArtifactUrl(indexUrl, entry.getUrl())) returns a response where result.isSuccess() is false, so the throw fires before size/digest checks.

Common situations: The skill artifact URL in the well-known index is broken or moved (404); the hosting service is down (5xx); the entry URL is relative and resolveArtifactUrl produced a wrong absolute URL; CDN/auth-gated artifact requiring credentials.

Related errors

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