What causes "Failed to parse zip file: " + e.getMessage()" in alibaba/nacos?

Check server logs for the full stack trace — the chained exception (e) identifies the exact cause.

alibaba/nacos · error · NacosApiException

PARSING_DATA_FAILED

PARSING_DATA_FAILED

Error message

Failed to parse zip file: " + e.getMessage()

What it means

Thrown by SkillZipParser.parseSkillFromZip as the catch-all for any non-NacosApiException exception during ZIP parsing. This covers failures in unzipToEntries (ZipArchiveInputStream errors, security-limit violations via NacosRuntimeException), parseSkillMarkdown (invalid YAML, missing frontmatter), and parseResources. The original exception is logged and its message is included in the error.

Solutions

Check server logs for the full stack trace — the chained exception (e) identifies the exact cause.
If the ZIP is corrupted, re-download or re-create it from the source.
If the error is a security-limit violation (too many entries, uncompressed size exceeded), raise nacos.ai.skill.zip.max-entries or nacos.ai.skill.zip.max-uncompressed-size-mb if the skill legitimately needs more.
If the error is a path-traversal rejection, inspect the ZIP for entries containing '..' or absolute paths and remove them.
If the error is YAML-related, validate the SKILL.md frontmatter syntax with a YAML linter before zipping.

Example fix

// before — ZIP contains a path-traversal entry
// entry: ../../../etc/passwd

// after — re-create ZIP without malicious entries
// zip -r skill.zip SKILL.md resources/  (from inside the skill directory)
// verify: unzip -l skill.zip  (no entries with '..')

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate ZIP structure before calling parseSkillFromZip
if (zipBytes == null || zipBytes.length == 0) {
    throw new IllegalArgumentException("ZIP is empty");
}
// Check ZIP magic bytes
if (zipBytes.length < 4 || (zipBytes[0] != 0x50 || zipBytes[1] != 0x4B)) {
    throw new IllegalArgumentException("Not a valid ZIP file (missing PK magic bytes)");
}

Type guard

public static boolean isValidZipArchive(byte[] zipBytes) {
    return zipBytes != null && zipBytes.length >= 4
        && zipBytes[0] == 0x50 && zipBytes[1] == 0x4B // PK magic
        && zipBytes.length <= SkillZipParser.resolveMaxUploadBytes();
}

Try / catch

try {
    Skill skill = SkillZipParser.parseSkillFromZip(zipBytes, namespaceId);
} catch (NacosApiException e) {
    if (ErrorCode.PARSING_DATA_FAILED.equals(e.getErrDetail())) {
        log.error("Failed to parse skill ZIP: {}", e.getErrMsg(), e);
        return ResponseEntity.badRequest()
            .body("Could not parse the ZIP file. Check the archive integrity and SKILL.md format. Detail: "
                + e.getErrMsg());
    }
    throw e;
}

Prevention

Validate the ZIP magic bytes (PK) before parsing to catch non-ZIP files early.
Run unzip -t skill.zip to test archive integrity before uploading.
Validate SKILL.md YAML frontmatter syntax with a YAML linter.
Inspect ZIP entries for path traversal ('..') before uploading.
Raise max-entries / max-uncompressed-size-mb if legitimate large skills are rejected.

When it happens

Trigger: Uploading a ZIP that triggers any unexpected exception during parsing: a corrupted ZIP archive that Apache Commons Compress cannot read; a path-traversal entry ('../') caught by SkillUtils.validatePathSafety; a ZIP bomb exceeding the uncompressed size limit; a SKILL.md with malformed YAML frontmatter; a resource entry with an invalid name pattern.

Common situations: Corrupted or truncated ZIP file from a failed download; a ZIP created by a tool that produces entries Apache Commons Compress cannot handle; a malicious or accidental path-traversal entry in the ZIP; exceeding the max-entries or max-uncompressed-size limits; SKILL.md YAML frontmatter that is syntactically broken (e.g. missing colon, unbalanced quotes).

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/utils/SkillZipParser.java:248

            if (StringUtils.isBlank(skillMdContent)) {
                throw new NacosApiException(NacosApiException.INVALID_PARAM,
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "SKILL.md file not found in zip");
            }
            
            Skill skill = parseSkillMarkdown(skillMdContent, namespaceId);
            List<ZipEntryData> resourceEntries =
                filterEntriesByPrefix(entries, getSkillPrefix(skillMdEntry.name));
            Map<String, SkillResource> resources =
                parseResources(resourceEntries, skill.getName(), SKILL_MD_FILE);
            skill.setResource(resources);
            
            return skill;
        } catch (NacosApiException e) {
            throw e;
        } catch (Exception e) {
            LOGGER.error("Failed to parse skill zip file", e);
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARSING_DATA_FAILED,
                "Failed to parse zip file: " + e.getMessage());
        }
    }
    
    /**
     * Parse multiple skills from a single zip archive. Supports zip files containing multiple skill subdirectories,
     * each with its own SKILL.md. If only one SKILL.md is found, returns a list with a single element.
     *
     * <p>Expected zip structure for multi-skill:
     * <pre>
     * skills.zip
     * ├── skill-a/
     * │   ├── SKILL.md
     * │   └── resource.txt
     * ├── skill-b/
     * │   ├── SKILL.md
     * │   └── template/prompt.md

View on GitHub (pinned to 9b989acdf1)