alibaba/nacos · error · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Required parameter 'skillName' when basedOnVersion is set

What it means

SkillDraftCreateForm.validate() implements a fork path: when `basedOnVersion` is set (non-blank), the request creates a new draft FROM an existing published version, so `skillCard` is ignored and `skillName` becomes mandatory to identify the source skill. A blank skillName in this fork mode fails with PARAMETER_MISSING. When basedOnVersion is absent, it falls through to super.validate() which requires skillCard instead.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/skills/admin/SkillDraftCreateForm.java:60

    
    private String commitMsg;
    
    /**
     * Parsed skill for create-draft after {@link #prepareCreateDraftRequest()}; not part of the serialized form.
     */
    private transient Skill resolvedInitialSkill;
    
    /**
     * The request form allow user create a new craft from current version. So if {@code basedOnVersion} is set,
     * {@code skillCard} will be ignored, and {@code skillName} is required. Otherwise, means users create a new skill,
     * so {@code skillCard} is required and {@code skillName} is ignored.
     */
    @Override
    public void validate() throws NacosApiException {
        fillDefaultNamespaceId();
        if (StringUtils.isNotBlank(basedOnVersion)) {
            if (StringUtils.isEmpty(getSkillName())) {
                throw new NacosApiException(NacosException.INVALID_PARAM,
                    ErrorCode.PARAMETER_MISSING,
                    "Required parameter 'skillName' when basedOnVersion is set");
            }
            return;
        }
        super.validate();
    }
    
    /**
     * Validates this request, normalizes {@link #setSkillName(String)} when the name only appears inside
     * {@code skillCard}, and caches the parsed skill for {@link #getResolvedInitialSkillOrNull()}.
     * <p>
     * Console and admin controllers must invoke this before {@code SkillProxy} / {@code SkillHandler}; handlers then
     * only forward to service or remote client without repeating validation.
     * </p>
     */
    public void prepareCreateDraftRequest() throws NacosApiException {
        validate();

View on GitHub (pinned to 9b989acdf1)

Solutions

1. When forking (basedOnVersion set), always include `skillName` of the skill to fork from.
2. If you actually want to create a brand-new skill, remove `basedOnVersion` and send `skillCard` instead.
3. Double-check the fork UI populates skillName from the source skill row.

Example fix

// before
{"basedOnVersion":"1.0.0","targetVersion":"1.1.0"}
// after
{"skillName":"my-skill","basedOnVersion":"1.0.0","targetVersion":"1.1.0"}

// Fork mode: basedOnVersion set => skillName required
if (basedOnVersion != null && !basedOnVersion.isBlank()
    && (skillName == null || skillName.isEmpty())) {
    throw new IllegalArgumentException("skillName is required when forking via basedOnVersion");
}

// TypeScript
const forkRequestValid = (r: {basedOnVersion?: string; skillName?: string}): boolean =>
  !r.basedOnVersion || !!r.skillName?.trim();

try {
    form.validate();
} catch (NacosApiException e) {
    // fork mode missing skillName — populate from the source skill
}

When it happens

Trigger: Calling create-draft with `basedOnVersion` set (e.g. `1.0.0`) but `skillName` blank. Common when forking: the client assumes the server knows which skill from context, but forking is cross-version of a NAMED skill.

Common situations: Frontend 'fork' button that sends only the source version and target version, omitting which skill to fork; assuming skillName is implied by namespace; confusion between create-new (skillCard required) and fork (skillName required) modes.

Related errors

• PARAMETER_MISSING
• PARAMETER_MISSING
• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISSING
• PARAMETER_MISSING

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