alibaba/nacos · warning · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

Skill zip file is empty

What it means

Thrown by SkillZipParser.parseSkillFromZip when the provided zipBytes array is null or has zero length. This is the first validation check before attempting to unzip. It fires when the caller passes an empty byte array where a ZIP archive is expected.

Source

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

                e.getMessage());
            return null;
        }
    }
    
    /**
     * Parse skill from zip file bytes. Zip size must not exceed the limit returned by
     * {@link #resolveMaxUploadBytes()} (configurable via {@value #CONFIG_MAX_UPLOAD_SIZE_MB}).
     * Text files are decoded as UTF-8; binary files (by extension) are stored as Base64 with metadata encoding=base64.
     *
     * @param zipBytes zip file bytes
     * @param namespaceId namespace ID
     * @return parsed skill
     * @throws NacosApiException if parsing failed or zip exceeds size limit
     */
    public static Skill parseSkillFromZip(byte[] zipBytes, String namespaceId)
        throws NacosApiException {
        if (zipBytes == null || zipBytes.length == 0) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Skill zip file is empty");
        }
        long maxUploadBytes = resolveMaxUploadBytes();
        if (zipBytes.length > maxUploadBytes) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "Skill zip size must not exceed "
                    + (maxUploadBytes / 1024 / 1024) + "MB, current: "
                    + (zipBytes.length / 1024 / 1024) + "MB");
        }
        try {
            List<ZipEntryData> entries = unzipToEntries(zipBytes);
            ZipEntryData skillMdEntry = findSkillMdEntry(entries);
            if (skillMdEntry == null) {
                throw new NacosApiException(NacosApiException.INVALID_PARAM,
                    ErrorCode.PARAMETER_VALIDATE_ERROR,
                    "SKILL.md file not found in zip");

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify the zipBytes array is non-null and has length > 0 before calling parseSkillFromZip.
2. If reading bytes from a file or stream, check the byte array length after reading and before passing to the parser.
3. Add a guard in calling code: if (zipBytes == null || zipBytes.length == 0) throw early with a descriptive error.
4. Trace upstream to find where the empty bytes originated — a failed download, a truncated read, or a logic error.

Example fix

// before — no guard before calling parser
Skill skill = SkillZipParser.parseSkillFromZip(bytes, namespaceId);

// after — validate non-empty first
if (bytes == null || bytes.length == 0) {
    throw new IllegalArgumentException("Skill ZIP bytes must not be null or empty");
}
Skill skill = SkillZipParser.parseSkillFromZip(bytes, namespaceId);

// Check zipBytes before calling parseSkillFromZip
if (zipBytes == null || zipBytes.length == 0) {
    throw new IllegalArgumentException("Skill ZIP bytes must not be null or empty");
}

public static boolean isNonEmptyZipBytes(byte[] zipBytes) {
    return zipBytes != null && zipBytes.length > 0;
}

try {
    Skill skill = SkillZipParser.parseSkillFromZip(zipBytes, namespaceId);
} catch (NacosApiException e) {
    if (ErrorCode.PARAMETER_VALIDATE_ERROR.equals(e.getErrDetail())
        && e.getErrMsg().contains("empty")) {
        return "The provided ZIP file is empty. Please provide a valid skill archive.";
    }
    throw e;
}

When it happens

Trigger: Calling parseSkillFromZip programmatically with a null or empty byte array. In the HTTP path, this is unlikely because validateAndExtractZipBytes (error 389) catches empty files first, but direct service-layer or test code can reach this method with empty bytes.

Common situations: A test calls parseSkillFromZip with an empty byte array; a service-layer method passes through a null after failed upstream processing; a ZIP download from a remote source returned an empty response body; a file read returned 0 bytes but the null/empty check upstream was bypassed.

Related errors

• PARAMETER_VALIDATE_ERROR
• PARSING_DATA_FAILED
• PARAMETER_VALIDATE_ERROR
• PARAMETER_VALIDATE_ERROR
• PARAMETER_VALIDATE_ERROR

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