alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter `skillCard.${fieldName}` not present

What it means

Thrown by validateSkillField when a required field on the parsed Skill object is null or empty. Called from validateSkill which checks name, description, and skillMd in sequence. The error message names the specific missing field via the fieldName parameter so the caller knows exactly which skillCard property is absent.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/utils/SkillRequestUtil.java:302

                String key = line.substring(0, colonIdx).trim();
                if (field.equals(key)) {
                    String value = line.substring(colonIdx + 1).trim();
                    // Strip surrounding quotes
                    if (value.length() >= 2 && ((value.startsWith("\"") && value.endsWith("\""))
                        || (value.startsWith("'") && value.endsWith("'")))) {
                        value = value.substring(1, value.length() - 1);
                    }
                    return value;
                }
            }
        }
        return null;
    }
    
    private static void validateSkillField(String fieldName, String fieldValue)
        throws NacosApiException {
        if (StringUtils.isEmpty(fieldValue)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING,
                "Required parameter `skillCard." + fieldName + "` not present");
        }
    }
    
    /**
     * Validate markdown content is present and has non-empty body after removing frontmatter.
     *
     * @param fieldPath field path used in error message
     * @param markdown markdown content to validate
     * @throws NacosApiException if markdown is missing or body is empty
     */
    public static void validateSkillMarkdownBody(String fieldPath, String markdown)
        throws NacosApiException {
        if (StringUtils.isEmpty(markdown)) {
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_MISSING,
                "Required parameter `" + fieldPath + "` not present");

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure skillCard JSON includes non-empty values for name, description, and skillMd.
Validate the JSON object client-side before submission: check each required key exists and has a non-blank string value.
If updating an existing skill, fetch the current skillCard first and merge changed fields rather than submitting a partial object.
Review the API spec for the full list of required fields on the Skill type.

Example fix

// before — skillCard missing skillMd field
{"name":"my-skill","description":"A test skill"}

// after — all required fields present
{"name":"my-skill","description":"A test skill","skillMd":"---\nname: my-skill\n---\n# Instructions\nDo the thing."}

Defensive patterns

Strategy: validation

Validate before calling

// Ensure all required Skill fields are non-blank before submitting
Skill skill = JacksonUtils.toObj(skillCardJson, Skill.class);
if (StringUtils.isBlank(skill.getName())) throw new IllegalArgumentException("name is required");
if (StringUtils.isBlank(skill.getDescription())) throw new IllegalArgumentException("description is required");
if (StringUtils.isBlank(skill.getSkillMd())) throw new IllegalArgumentException("skillMd is required");

Type guard

public static boolean hasRequiredSkillFields(Skill skill) {
    return skill != null
        && StringUtils.isNotBlank(skill.getName())
        && StringUtils.isNotBlank(skill.getDescription())
        && StringUtils.isNotBlank(skill.getSkillMd());
}

Try / catch

try {
    SkillRequestUtil.validateSkill(skill);
} catch (NacosApiException e) {
    if (ErrorCode.PARAMETER_MISSING.equals(e.getErrDetail())) {
        // Extract field name from message and surface to UI
        String field = extractFieldNameFromMessage(e.getErrMsg());
        return "Missing required field: " + field;
    }
    throw e;
}

Prevention

Define required-field checks in the frontend form before submission.
Use a Skill DTO/builder that enforces non-null for required fields at construction time.
Document the required skillCard fields in your API client docs.

When it happens

Trigger: POST/PUT to a skill endpoint where the skillCard JSON deserializes successfully but one of the required fields — name, description, or skillMd — is null, empty string, or omitted from the JSON object. The first missing field encountered causes the throw.

Common situations: Developer includes name and description but forgets skillMd; a field is present but set to empty string ""; the frontend form has a bug that strips a field before submission; a default Skill template is used that has placeholder nulls.

Related errors

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