alibaba/nacos · error · NacosException

Failed to create skill well-known archive: " + e.getMessage(

Error message

Failed to create skill well-known archive: " + e.getMessage()

What it means

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.

Source

Thrown at ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/NacosSkillsRegistryService.java:389

                    SkillUtils.toMarkdown(skill).getBytes(StandardCharsets.UTF_8));
                if (skill.getResource() != null && !skill.getResource().isEmpty()) {
                    List<SkillResource> resources = new ArrayList<>();
                    for (SkillResource each : skill.getResource().values()) {
                        if (each != null && StringUtils.isNotBlank(each.getName())) {
                            resources.add(each);
                        }
                    }
                    resources.sort(Comparator.comparing(this::buildRelativePath));
                    for (SkillResource each : resources) {
                        addZipEntry(zip, buildRelativePath(each),
                            each.getContent() == null ? new byte[0]
                                : each.getContent().getBytes(StandardCharsets.UTF_8));
                    }
                }
            }
            return output.toByteArray();
        } catch (Exception e) {
            throw new NacosException(NacosException.SERVER_ERROR,
                "Failed to create skill well-known archive: " + e.getMessage(), e);
        }
    }
    
    private void addZipEntry(ZipOutputStream zip, String path, byte[] bytes) throws Exception {
        SkillUtils.validatePathSafety(path);
        ZipEntry entry = new ZipEntry(path);
        entry.setTime(STABLE_ZIP_ENTRY_TIME);
        zip.putNextEntry(entry);
        zip.write(bytes);
        zip.closeEntry();
    }
    
    private String fileUrl(String skillName, String file) {
        return encodePathSegment(skillName) + "/" + encodePath(file);
    }
    
    private String archiveUrl(String skillName) {

View on GitHub (pinned to 9b989acdf1)

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.

Defensive patterns

Strategy: try-catch

Try / catch

// Server-side failure: retry once for transient I/O, then surface the chained cause
try {
    byte[] archive = ardClient.downloadSkillArchive(namespaceId, skillName, version);
    return archive;
} catch (NacosException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR && attempts < MAX_ATTEMPTS) {
        backoffThenRetry();
    } else {
        log.error("Failed to build skill archive: {}", e.getMessage(), e);
        throw new RuntimeException("Skill archive unavailable, please retry later", e);
    }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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