alibaba/nacos · error · NacosApiException

404

404

Error message

Skill not found in well-known index:  + skillName

What it means

Thrown by SkillWellKnownImportService.findSkillEntry as NacosApiException with code NOT_FOUND (404) and ErrorCode.RESOURCE_NOT_FOUND when the requested skill name is not present in the resolved well-known skill index list. The index was fetched but none of its WellKnownSkillEntry items matched the requested name.

Source

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

        AiResourceImportCandidate result = new AiResourceImportCandidate();
        result.setResourceType(RESOURCE_TYPE_SKILL);
        result.setExternalId(entry.getName());
        result.setName(entry.getName());
        result.setDescription(entry.getDescription());
        result.setMetadata(buildMetadata(entry, resolvedIndex));
        return result;
    }
    
    private WellKnownSkillEntry findSkillEntry(List<WellKnownSkillEntry> skills, String skillName)
        throws NacosException {
        if (CollectionUtils.isNotEmpty(skills)) {
            for (WellKnownSkillEntry each : skills) {
                if (each != null && StringUtils.equals(skillName, each.getName())) {
                    return each;
                }
            }
        }
        throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
            "Skill not found in well-known index: " + skillName);
    }
    
    private byte[] fetchSkillZip(ResolvedWellKnownIndex resolvedIndex,
        WellKnownSkillEntry entry) throws Exception {
        if (resolvedIndex.getVersion() == WellKnownIndexVersion.V0_2_0) {
            return fetchVersion020SkillZip(resolvedIndex, entry);
        }
        return fetchVersion010SkillZip(resolvedIndex, entry);
    }
    
    private byte[] fetchVersion010SkillZip(ResolvedWellKnownIndex resolvedIndex,
        WellKnownSkillEntry entry) throws Exception {
        String base = resolvedIndex.getWellKnownBase();
        List<String> files = normalizeFiles(entry.getFiles());
        ByteArrayOutputStream output = new ByteArrayOutputStream();
        try (ZipOutputStream zip = new ZipOutputStream(output, StandardCharsets.UTF_8)) {
            for (String each : files) {

View on GitHub (pinned to 9b989acdf1)

Solutions

1. List the well-known index entries first and use the exact name returned.
2. Verify the skill still exists in the target well-known index version (V0_1_0 vs V0_2_0).
3. Match the name exactly including case and separators; do not rely on fuzzy matching.

Example fix

// before
importSkill("WeatherSkill"); // wrong case -> 404

// after: use the exact name from the index
WellKnownSkillEntry e = index.stream()
    .filter(s -> s.getName().equalsIgnoreCase("weatherSkill"))
    .findFirst().orElseThrow();
importSkill(e.getName());

boolean skillInIndex(List<WellKnownSkillEntry> skills, String name) {
    return skills != null && skills.stream()
        .anyMatch(s -> s != null && StringUtils.equals(name, s.getName()));
}

static boolean skillResolvable(List<WellKnownSkillEntry> skills, String name) {
    return skills != null && name != null && skills.stream()
        .anyMatch(s -> s != null && name.equals(s.getName()));
}

try {
    service.importSkill(index, skillName);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.NOT_FOUND
        && e.getErrorCode() == ErrorCode.RESOURCE_NOT_FOUND) {
        // list index and correct the name
    } else throw e;
}

When it happens

Trigger: Importing a well-known skill by name (AI registry skill import) where the name does not exactly equal any entry.getName() in the resolved index. Triggered by the skill import API/service when the well-known index is reachable but the skill is absent.

Common situations: Skill name typo; referencing a skill removed from the index; version skew between client expectations and the published well-known index; case sensitivity in the name comparison (StringUtils.equals is exact).

Related errors

• 10000
• 20002
• PARAMETER_MISSING
• RESOURCE_NOT_FOUND
• RESOURCE_NOT_FOUND

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