{"record":{"id":"a5b0cd780241e09d","repo":"alibaba/nacos","slug":"failed-to-create-skill-well-known-archive-e-g","errorCode":null,"errorMessage":"Failed to create skill well-known archive: \" + e.getMessage()","messagePattern":"Failed to create skill well-known archive: \" \\+ e\\.getMessage\\(\\)","errorType":"exception","errorClass":"NacosException","httpStatus":500,"severity":"error","filePath":"ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/NacosSkillsRegistryService.java","lineNumber":389,"sourceCode":"                    SkillUtils.toMarkdown(skill).getBytes(StandardCharsets.UTF_8));\n                if (skill.getResource() != null && !skill.getResource().isEmpty()) {\n                    List<SkillResource> resources = new ArrayList<>();\n                    for (SkillResource each : skill.getResource().values()) {\n                        if (each != null && StringUtils.isNotBlank(each.getName())) {\n                            resources.add(each);\n                        }\n                    }\n                    resources.sort(Comparator.comparing(this::buildRelativePath));\n                    for (SkillResource each : resources) {\n                        addZipEntry(zip, buildRelativePath(each),\n                            each.getContent() == null ? new byte[0]\n                                : each.getContent().getBytes(StandardCharsets.UTF_8));\n                    }\n                }\n            }\n            return output.toByteArray();\n        } catch (Exception e) {\n            throw new NacosException(NacosException.SERVER_ERROR,\n                \"Failed to create skill well-known archive: \" + e.getMessage(), e);\n        }\n    }\n    \n    private void addZipEntry(ZipOutputStream zip, String path, byte[] bytes) throws Exception {\n        SkillUtils.validatePathSafety(path);\n        ZipEntry entry = new ZipEntry(path);\n        entry.setTime(STABLE_ZIP_ENTRY_TIME);\n        zip.putNextEntry(entry);\n        zip.write(bytes);\n        zip.closeEntry();\n    }\n    \n    private String fileUrl(String skillName, String file) {\n        return encodePathSegment(skillName) + \"/\" + encodePath(file);\n    }\n    \n    private String archiveUrl(String skillName) {","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/NacosSkillsRegistryService.java#L371-L407","documentation":"While building the downloadable well-known archive (zip) for a skill, the server wraps any unexpected exception and rethrows it as a NacosException with code SERVER_ERROR (HTTP 500). This is an internal failure, not a client validation error; the original cause is chained as the exception's cause and surfaced in the message.","triggerScenarios":"Requesting a skill archive download/export when assembling the zip fails — e.g. a resource whose content cannot be encoded, an IO error writing the ZipOutputStream, or a path that fails SkillUtils.validatePathSafety during addZipEntry.","commonSituations":"Corrupted or missing skill resource in storage; a resource entry with a name that violates zip path safety; transient I/O failure on the server; encoding failure on binary content.","solutions":["Retry the request once after a short delay in case the cause was transient I/O.","Inspect the server logs for the chained cause (the message echoes e.getMessage()) to find the real failure.","If a specific resource is implicated, re-save or re-upload the skill package so storage is consistent.","If it persists, report the chained cause; this is a server-side defect, not a client input error."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Server-side failure: retry once for transient I/O, then surface the chained cause\ntry {\n    byte[] archive = ardClient.downloadSkillArchive(namespaceId, skillName, version);\n    return archive;\n} catch (NacosException e) {\n    if (e.getErrCode() == NacosException.SERVER_ERROR && attempts < MAX_ATTEMPTS) {\n        backoffThenRetry();\n    } else {\n        log.error(\"Failed to build skill archive: {}\", e.getMessage(), e);\n        throw new RuntimeException(\"Skill archive unavailable, please retry later\", e);\n    }\n}","preventionTips":["Retry once with backoff since the cause may be transient I/O.","Check server logs for the chained cause when it persists.","Re-save/re-upload the skill if storage appears inconsistent.","Treat persistent failures as a server defect, not a client input problem."],"tags":["skill","server-error","archive","io","ai"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}