{"record":{"id":"2fb585cab4e17d2f","repo":"alibaba/nacos","slug":"404-2fb585","errorCode":"404","errorMessage":"Skill not found in well-known index:  + skillName","messagePattern":"Skill not found in well-known index:  \\+ skillName","errorType":"error_code","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/skill/SkillWellKnownImportService.java","lineNumber":297,"sourceCode":"        AiResourceImportCandidate result = new AiResourceImportCandidate();\n        result.setResourceType(RESOURCE_TYPE_SKILL);\n        result.setExternalId(entry.getName());\n        result.setName(entry.getName());\n        result.setDescription(entry.getDescription());\n        result.setMetadata(buildMetadata(entry, resolvedIndex));\n        return result;\n    }\n    \n    private WellKnownSkillEntry findSkillEntry(List<WellKnownSkillEntry> skills, String skillName)\n        throws NacosException {\n        if (CollectionUtils.isNotEmpty(skills)) {\n            for (WellKnownSkillEntry each : skills) {\n                if (each != null && StringUtils.equals(skillName, each.getName())) {\n                    return each;\n                }\n            }\n        }\n        throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,\n            \"Skill not found in well-known index: \" + skillName);\n    }\n    \n    private byte[] fetchSkillZip(ResolvedWellKnownIndex resolvedIndex,\n        WellKnownSkillEntry entry) throws Exception {\n        if (resolvedIndex.getVersion() == WellKnownIndexVersion.V0_2_0) {\n            return fetchVersion020SkillZip(resolvedIndex, entry);\n        }\n        return fetchVersion010SkillZip(resolvedIndex, entry);\n    }\n    \n    private byte[] fetchVersion010SkillZip(ResolvedWellKnownIndex resolvedIndex,\n        WellKnownSkillEntry entry) throws Exception {\n        String base = resolvedIndex.getWellKnownBase();\n        List<String> files = normalizeFiles(entry.getFiles());\n        ByteArrayOutputStream output = new ByteArrayOutputStream();\n        try (ZipOutputStream zip = new ZipOutputStream(output, StandardCharsets.UTF_8)) {\n            for (String each : files) {","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/plugin-default-impl/nacos-default-ai-importer-plugin/src/main/java/com/alibaba/nacos/plugin/ai/importer/defaultimpl/skill/SkillWellKnownImportService.java#L279-L315","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["List the well-known index entries first and use the exact name returned.","Verify the skill still exists in the target well-known index version (V0_1_0 vs V0_2_0).","Match the name exactly including case and separators; do not rely on fuzzy matching."],"exampleFix":"// before\nimportSkill(\"WeatherSkill\"); // wrong case -> 404\n\n// after: use the exact name from the index\nWellKnownSkillEntry e = index.stream()\n    .filter(s -> s.getName().equalsIgnoreCase(\"weatherSkill\"))\n    .findFirst().orElseThrow();\nimportSkill(e.getName());","handlingStrategy":"validation","validationCode":"boolean skillInIndex(List<WellKnownSkillEntry> skills, String name) {\n    return skills != null && skills.stream()\n        .anyMatch(s -> s != null && StringUtils.equals(name, s.getName()));\n}","typeGuard":"static boolean skillResolvable(List<WellKnownSkillEntry> skills, String name) {\n    return skills != null && name != null && skills.stream()\n        .anyMatch(s -> s != null && name.equals(s.getName()));\n}","tryCatchPattern":"try {\n    service.importSkill(index, skillName);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == NacosException.NOT_FOUND\n        && e.getErrorCode() == ErrorCode.RESOURCE_NOT_FOUND) {\n        // list index and correct the name\n    } else throw e;\n}","preventionTips":["List the well-known index and use the exact entry name.","Names are compared with StringUtils.equals (case-sensitive, exact).","Handle 404 by re-listing the index for the resolved version."],"tags":["ai","skill","import","not-found","well-known"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}