{"record":{"id":"c60985e4a492e6e4","repo":"alibaba/nacos","slug":"parameter-validate-error-c60985","errorCode":"PARAMETER_VALIDATE_ERROR","errorMessage":"Failed to read agentspec zip archive","messagePattern":"Failed to read agentspec zip archive","errorType":"validation","errorClass":"NacosApiException","httpStatus":400,"severity":"warning","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java","lineNumber":400,"sourceCode":"                importedNames\n                    .add(uploadSingleAgentSpecFromZip(namespaceId, each.getZipBytes(), overwrite));\n            }\n            return String.format(\"Imported %d agentspecs: %s\", importedNames.size(),\n                String.join(\", \", importedNames));\n        }\n        // Not a seed archive: treat as a single AgentSpec ZIP\n        return uploadSingleAgentSpecFromZip(namespaceId, zipBytes, overwrite);\n    }\n    \n    /**\n     * Try to read the ZIP as a multi-spec seed archive. Returns empty list if it's a regular single-spec ZIP.\n     */\n    private List<AgentSpecSeedArchiveReader.AgentSpecPackage> readUploadPackages(byte[] zipBytes)\n        throws NacosException {\n        try (ByteArrayInputStream inputStream = new ByteArrayInputStream(zipBytes)) {\n            return AgentSpecSeedArchiveReader.read(inputStream);\n        } catch (IOException e) {\n            throw new NacosApiException(NacosException.INVALID_PARAM,\n                ErrorCode.PARAMETER_VALIDATE_ERROR, e,\n                \"Failed to read agentspec zip archive\");\n        }\n    }\n    \n    /**\n     * Upload a single AgentSpec from ZIP bytes.\n     * If overwrite=true, replaces existing draft or creates new. Otherwise fails on working version conflict.\n     */\n    private String uploadSingleAgentSpecFromZip(String namespaceId, byte[] zipBytes,\n        boolean overwrite)\n        throws NacosException {\n        // Step 1: Parse ZIP and validate agentspec name\n        AgentSpec agentSpec = AgentSpecZipParser.parseAgentSpecFromZip(zipBytes, namespaceId);\n        if (agentSpec == null || StringUtils.isBlank(agentSpec.getName())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"AgentSpec name is required\");\n        }","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java#L382-L418","documentation":"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.","triggerScenarios":"Uploading a file that is not a valid ZIP archive, a truncated/corrupt ZIP, or a ZIP that cannot be streamed by AgentSpecSeedArchiveReader.","commonSituations":"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.","solutions":["Re-export the AgentSpec as a standard ZIP (deflate, no special compression) and re-upload.","Verify the file is complete (match byte size / checksum) before uploading.","Open the ZIP locally with a standard archiver to confirm it is not corrupt.","Ensure the upload endpoint receives the raw bytes without re-encoding (e.g. base64)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate the ZIP client-side before upload\ntry (java.util.zip.ZipFile zf = new java.util.zip.ZipFile(zipFile)) {\n    // iteration succeeds only for a valid ZIP\n} catch (IOException e) {\n    throw new IllegalArgumentException(\"Uploaded file is not a valid ZIP\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    service.uploadAgentSpec(namespaceId, zipBytes, overwrite);\n} catch (NacosApiException e) {\n    if (e.getErrCode() == NacosException.INVALID_PARAM\n        && e.getMessage().contains(\"zip archive\")) {\n        // ask user to re-export the ZIP\n        return \"Invalid archive; please re-export as a standard ZIP.\";\n    }\n    throw e;\n}","preventionTips":["Open the ZIP with a standard archiver before uploading to confirm integrity.","Send raw bytes; avoid base64 or other transport encodings that corrupt the archive.","Use the official AgentSpec packaging tool to produce the ZIP."],"tags":["agentspec","upload","zip","validation","io"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}