alibaba/nacos · warning · NacosApiException
PARAMETER_MISSING
PARAMETER_MISSING
Error message
Skill name is required
What it means
An INVALID_PARAM (HTTP 400, ErrorCode PARAMETER_MISSING/10000) from uploadSkillFromZip: after parsing the ZIP, the resulting Skill is null or its name is blank. The skill name is read from the YAML front-matter of SKILL.md (the name: key); if the front-matter omits name or the ZIP is malformed so parsing yields null, the upload is rejected before any storage write.
Source
Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/skills/SkillOperationServiceImpl.java:185
AiResourceIndexMaintenanceService resourceIndexMaintenanceService) {
if (resourceIndexMaintenanceService != null) {
this.resourceIndexMaintenanceService = resourceIndexMaintenanceService;
}
}
/**
* Upload a skill from a ZIP archive.
*
* <p>Flow: parse ZIP -> validate name -> resolve version -> check existing meta.
* If overwrite=true, replaces the current editing draft or creates a new one.
* If overwrite=false, fails when a working version (editing/reviewing) already exists.</p>
*/
@Override
public String uploadSkillFromZip(SkillUploadRequest request) throws NacosException {
Skill skill = SkillZipParser.parseSkillFromZip(request.getZipBytes(),
request.getNamespaceId());
if (skill == null || StringUtils.isBlank(skill.getName())) {
throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
"Skill name is required");
}
List<UploadVersionCandidate> uploadVersions = resolveUploadVersionCandidates(skill,
request.getTargetVersion());
return doUploadSingleSkill(request.getNamespaceId(), skill, uploadVersions,
request.isOverwrite(), request.getUploadAction(), request.getCommitMsg());
}
@Override
public List<SkillUploadPrecheckResult> precheckUploadSkillFromZip(String namespaceId,
byte[] zipBytes) throws NacosException {
SkillZipParser.MultiSkillParseResult parseResult =
SkillZipParser.parseMultipleSkillsFromZip(zipBytes, namespaceId);
List<SkillUploadPrecheckResult> results = new ArrayList<>(
parseResult.getFailures().size() + parseResult.getSkills().size());
for (SkillZipParser.ParseFailure failure : parseResult.getFailures()) {
results.add(buildPrecheckParseFailureResult(namespaceId, failure));
}View on GitHub (pinned to 9b989acdf1)
Solutions
- Open the ZIP, edit SKILL.md front-matter to include 'name: <skill-name>' (and 'description:'), then re-zip and re-upload.
- Verify the ZIP contains a SKILL.md entry at the expected location.
- Run precheckUploadSkillFromZip first to surface the parse problem before attempting the real upload.
Example fix
// before — SKILL.md front-matter missing name --- description: A weather tool --- // after --- name: weather-tool description: A weather tool ---
Defensive patterns
Strategy: validation
Validate before calling
// Parse locally and assert the name is present before uploading.
Skill parsed = SkillZipParser.parseSkillFromZip(zipBytes, ns);
if (parsed == null || StringUtils.isBlank(parsed.getName())) {
// fix SKILL.md front-matter (add 'name:') before retrying
return;
}
skillOp.uploadSkillFromZip(req); Prevention
- Always include 'name:' and 'description:' in SKILL.md YAML front-matter.
- Run precheckUploadSkillFromZip before the real upload to catch missing fields.
- Build ZIPs with the expected SKILL.md entry layout.
When it happens
Trigger: Uploading a single-skill ZIP whose SKILL.md front-matter has no name: key, or a ZIP so malformed that SkillZipParser.parseSkillFromZip returns null.
Common situations: Hand-authored SKILL.md missing the name field; using a plain markdown file instead of a proper skill ZIP; an older skill format that put the name elsewhere; ZIP built without the expected entry layout.
Related errors
AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14).
Data as JSON: /api/errors/83814cd369d1ffcc.
Report an issue: GitHub.