alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Skill name is required in YAML front matter

What it means

Once front matter matches, a simple line-based YAML reader extracts the top-level key name (keys are case-sensitive). If name is blank, the parser throws PARAMETER_MISSING because every skill needs an identity.

Source

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

    private static Skill parseSkillMarkdown(String markdownContent, String namespaceId)
        throws NacosApiException {
        Matcher matcher = YAML_FRONT_MATTER.matcher(markdownContent);
        
        if (!matcher.matches()) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "SKILL.md must contain YAML front matter (---)");
        }
        
        String yamlContent = matcher.group(1);
        
        Map<String, String> yamlMap = parseYamlFrontMatter(yamlContent);
        
        String name = yamlMap.get("name");
        String description = yamlMap.get("description");
        
        if (StringUtils.isBlank(name)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING,
                "Skill name is required in YAML front matter");
        }
        
        if (StringUtils.isBlank(description)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING,
                "Skill description is required in YAML front matter");
        }
        
        if (!SkillRequestUtil.hasNonFrontmatterContent(markdownContent)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING,
                "Skill markdown body is required");
        }
        
        Skill skill = new Skill();
        skill.setNamespaceId(namespaceId);

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Add a top-level name: <value> line at column 0 inside the front matter.
  2. Ensure the value after the colon is non-empty.
  3. Check spelling and casing: the key must be exactly name.

Example fix

// before
---
description: Does things.
---

// after
---
name: my-skill
description: Does things.
---
Defensive patterns

Strategy: validation

Validate before calling

// Ensure the front matter has a non-empty lowercase 'name' at column 0
Map<String,String> fm = SkillZipParser.parseYamlFrontMatterFromMarkdown(md);
if (StringUtils.isBlank(fm.get("name"))) {
    throw new IllegalArgumentException("Add a top-level 'name:' to SKILL.md front matter");
}

Try / catch

try {
    skillClient.upload(zipBytes);
} catch (NacosApiException e) {
    if (e.getErrorCode() == ErrorCode.PARAMETER_MISSING.getCode()
            && e.getMessage().contains("name")) {
        notifyUser("SKILL.md is missing the required 'name' field");
    }
    throw e;
}

Prevention

When it happens

Trigger: Front matter is present and well-delimited, but the name: line is missing, empty (name:), or keyed with different casing/indentation such as Name:, skillName:, or an indented name.

Common situations: Using Name instead of name; indenting name under another key (the reader only treats column-0 keys as top-level for name/description); leaving name: with no value.

Related errors

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