alibaba/nacos · error · IllegalArgumentException

Invalid ZIP data: too short ({length} bytes)

Error message

Invalid ZIP data: too short ({length} bytes)

What it means

Thrown by SkillUtils.validateZipBytes as an IllegalArgumentException when the byte array is null or shorter than 30 bytes (ZIP_MIN_SIZE, the length of a ZIP local file header). It is a pre-check before reading any magic bytes, protecting the caller from ArrayIndexOutOfBoundsException and detecting truncated or empty downloads.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/skills/SkillUtils.java:202

     * @param target  the resolved target path
     * @throws SecurityException if target escapes baseDir
     */
    public static void validatePathContainment(Path baseDir, Path target) {
        if (!target.normalize().startsWith(baseDir.normalize())) {
            throw new SecurityException(
                "Path escapes target directory: " + target + " is outside " + baseDir);
        }
    }
    
    /**
     * Validate that byte array is a valid ZIP file by checking the magic number header.
     *
     * @param data the byte array to validate
     * @throws IllegalArgumentException if data is null, too short, or does not have ZIP magic header
     */
    public static void validateZipBytes(byte[] data) {
        if (data == null || data.length < ZIP_MIN_SIZE) {
            throw new IllegalArgumentException(
                "Invalid ZIP data: too short (" + (data == null ? 0 : data.length) + " bytes)");
        }
        for (int i = 0; i < ZIP_MAGIC.length; i++) {
            if (data[i] != ZIP_MAGIC[i]) {
                throw new IllegalArgumentException(
                    "Invalid ZIP data: missing ZIP magic header (PK\\x03\\x04)");
            }
        }
    }
    
    /**
     * Validate all ZIP entry paths for path traversal and absolute paths.
     *
     * <p>Scans entry names only without decompressing content, so it is lightweight
     * and suitable for validating downloaded ZIP bytes on the client side.</p>
     *
     * @param data the ZIP byte array to validate
     * @throws SecurityException if any entry contains path traversal or absolute path

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify the download completed and the Content-Length matches before calling validateZipBytes.
2. Check for null or data.length >= 30 before invoking, and surface a clearer download error to the user.
3. Re-fetch the skill bundle from the Nacos server and retry the sync.

Example fix

// before
byte[] data = downloadSkillZip(id); // returned truncated 10 bytes
SkillUtils.validateZipBytes(data); // throws

// after
byte[] data = downloadSkillZip(id);
if (data == null || data.length < 30) {
    throw new IOException("Skill bundle download is empty or truncated");
}
SkillUtils.validateZipBytes(data); // ok

static boolean isPlausibleZip(byte[] data) {
    return data != null && data.length >= 30;
}
if (!isPlausibleZip(data)) {
    throw new IOException("Skill bundle is empty or truncated (" + (data == null ? 0 : data.length) + " bytes)");
}
SkillUtils.validateZipBytes(data);

static boolean hasZipMinSize(byte[] data) {
    return data != null && data.length >= 30;
}

try {
    SkillUtils.validateZipBytes(data);
} catch (IllegalArgumentException e) {
    // re-fetch the bundle or report download failure
    throw new IOException("Invalid skill bundle, please re-download", e);
}

When it happens

Trigger: Calling SkillUtils.validateZipBytes(data) where data == null or data.length < 30. Common when a skill download returned an empty/short body or a corrupted/truncated byte array was passed from toZipBytes.

Common situations: Network download of a skill bundle was interrupted, leaving a partial body; a base64 decode of an empty content field produced a zero-length array; a resource was misconfigured and the ZIP payload is missing entirely.

Related errors

• Invalid ZIP data: missing ZIP magic header (PK\x03\x04)
• Absolute path not allowed: {path}
• Base directory cannot be blank
• Skill directory name cannot be blank
• Skill directory already exists: {skillDir}

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