alibaba/nacos · warning · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

Failed to read agentspec zip archive

What it means

Thrown by AgentSpecOperationServiceImpl.readUploadPackages when AgentSpecSeedArchiveReader.read() throws an IOException while interpreting the uploaded bytes as a ZIP. The bytes are not a parseable AgentSpec ZIP (corrupt, truncated, or not a ZIP at all). Reported as PARAMETER_VALIDATE_ERROR (HTTP 400) because the input is invalid.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java:400

                importedNames
                    .add(uploadSingleAgentSpecFromZip(namespaceId, each.getZipBytes(), overwrite));
            }
            return String.format("Imported %d agentspecs: %s", importedNames.size(),
                String.join(", ", importedNames));
        }
        // Not a seed archive: treat as a single AgentSpec ZIP
        return uploadSingleAgentSpecFromZip(namespaceId, zipBytes, overwrite);
    }
    
    /**
     * Try to read the ZIP as a multi-spec seed archive. Returns empty list if it's a regular single-spec ZIP.
     */
    private List<AgentSpecSeedArchiveReader.AgentSpecPackage> readUploadPackages(byte[] zipBytes)
        throws NacosException {
        try (ByteArrayInputStream inputStream = new ByteArrayInputStream(zipBytes)) {
            return AgentSpecSeedArchiveReader.read(inputStream);
        } catch (IOException e) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR, e,
                "Failed to read agentspec zip archive");
        }
    }
    
    /**
     * Upload a single AgentSpec from ZIP bytes.
     * If overwrite=true, replaces existing draft or creates new. Otherwise fails on working version conflict.
     */
    private String uploadSingleAgentSpecFromZip(String namespaceId, byte[] zipBytes,
        boolean overwrite)
        throws NacosException {
        // Step 1: Parse ZIP and validate agentspec name
        AgentSpec agentSpec = AgentSpecZipParser.parseAgentSpecFromZip(zipBytes, namespaceId);
        if (agentSpec == null || StringUtils.isBlank(agentSpec.getName())) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "AgentSpec name is required");
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Re-export the AgentSpec as a standard ZIP (deflate, no special compression) and re-upload.
  2. Verify the file is complete (match byte size / checksum) before uploading.
  3. Open the ZIP locally with a standard archiver to confirm it is not corrupt.
  4. Ensure the upload endpoint receives the raw bytes without re-encoding (e.g. base64).
Defensive patterns

Strategy: validation

Validate before calling

// Validate the ZIP client-side before upload
try (java.util.zip.ZipFile zf = new java.util.zip.ZipFile(zipFile)) {
    // iteration succeeds only for a valid ZIP
} catch (IOException e) {
    throw new IllegalArgumentException("Uploaded file is not a valid ZIP", e);
}

Try / catch

try {
    service.uploadAgentSpec(namespaceId, zipBytes, overwrite);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM
        && e.getMessage().contains("zip archive")) {
        // ask user to re-export the ZIP
        return "Invalid archive; please re-export as a standard ZIP.";
    }
    throw e;
}

Prevention

When it happens

Trigger: Uploading a file that is not a valid ZIP archive, a truncated/corrupt ZIP, or a ZIP that cannot be streamed by AgentSpecSeedArchiveReader.

Common situations: Uploading a .tar.gz or raw file renamed to .zip; an interrupted upload producing partial bytes; the ZIP uses an unsupported encoding or compression method.

Related errors

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