What causes "skillCard is invalid. Can't be parsed." in alibaba/nacos?

Validate that skillCard is parseable JSON before submitting — use JSON.parse(skillCard) in the browser or Jackson ObjectMapper.readValue in Java.

alibaba/nacos · error · NacosApiException

PARAMETER_VALIDATE_ERROR

PARAMETER_VALIDATE_ERROR

Error message

skillCard is invalid. Can't be parsed.

What it means

Thrown by SkillRequestUtil.parseSkill when JacksonUtils.toObj fails to deserialize the skillCard JSON string from SkillDetailForm into a Skill object. The catch block intercepts NacosDeserializationException and converts it to a PARAMETER_VALIDATE_ERROR with HTTP 400, telling the caller the skillCard field is not valid JSON or does not match the Skill schema.

Source

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

    /**
     * Parse Skill request form to {@link Skill}.
     *
     * @param skillDetailForm skill detail form.
     * @return skill
     * @throws NacosApiException if parse failed or request parameter is conflicted.
     */
    public static Skill parseSkill(SkillDetailForm skillDetailForm) throws NacosApiException {
        try {
            Skill result =
                JacksonUtils.toObj(skillDetailForm.getSkillCard(), new TypeReference<>() {
                });
            validateSkill(result);
            return result;
        } catch (NacosDeserializationException e) {
            LOGGER
                .error(String.format("Deserialize %s from %s failed, ", Skill.class.getSimpleName(),
                    skillDetailForm.getSkillCard()), e);
            throw new NacosApiException(NacosApiException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR,
                "skillCard is invalid. Can't be parsed.");
        }
    }
    
    /**
     * Validate skill is legal.
     *
     * @param skill skill
     * @throws NacosApiException if skill is illegal.
     */
    public static void validateSkill(Skill skill) throws NacosApiException {
        validateSkillField("name", skill.getName());
        validateSkillField("description", skill.getDescription());
        validateSkillMarkdownBody("skillCard.skillMd", skill.getSkillMd());
    }
    
    /**

View on GitHub (pinned to 9b989acdf1)

Solutions

Validate that skillCard is parseable JSON before submitting — use JSON.parse(skillCard) in the browser or Jackson ObjectMapper.readValue in Java.
Ensure the skillCard JSON object has the correct top-level fields: name (string), description (string), skillMd (string), and optionally version, namespaceId, resource.
Check for common JSON errors: trailing commas, unescaped quotes inside string values, missing closing braces.
If building skillCard programmatically, use JacksonUtils.toJson(skillObject) rather than string concatenation.

Example fix

// before — hand-crafted JSON string with a trailing comma
String skillCard = "{\"name\":\"my-skill\",\"description\":\"test\",\"skillMd\":\"---\\nname: my-skill\\n---\\n# Body\",}";

// after — build via Jackson to guarantee valid JSON
ObjectNode node = JacksonUtils.createInstance().createObjectNode();
node.put("name", "my-skill");
node.put("description", "test");
node.put("skillMd", "---\nname: my-skill\n---\n# Body");
String skillCard = JacksonUtils.toJson(node);

Defensive patterns

Strategy: validation

Validate before calling

// Validate skillCard is valid JSON matching Skill schema before sending
try {
    Skill parsed = JacksonUtils.toObj(skillCardJson, Skill.class);
} catch (Exception e) {
    throw new IllegalArgumentException("skillCard is not valid JSON: " + e.getMessage());
}

Type guard

public static boolean isValidSkillCardJson(String skillCard) {
    if (StringUtils.isBlank(skillCard)) return false;
    try {
        JacksonUtils.toObj(skillCard, Skill.class);
        return true;
    } catch (Exception e) {
        return false;
    }
}

Try / catch

try {
    Skill skill = SkillRequestUtil.parseSkill(skillDetailForm);
} catch (NacosApiException e) {
    if (ErrorCode.PARAMETER_VALIDATE_ERROR.equals(e.getErrDetail())) {
        return ResponseEntity.badRequest().body("Invalid skillCard JSON: " + e.getErrMsg());
    }
    throw e;
}

Prevention

Always build skillCard JSON using a JSON serializer (Jackson) rather than string concatenation.
Validate JSON parseability client-side before form submission.
Use a JSON linter on the skillCard string to catch syntax errors early.
When copy-pasting skillCard content, verify it is JSON (not YAML or markdown).

When it happens

Trigger: POST/PUT to a skill create or update endpoint (admin or console) where the skillCard form field contains malformed JSON (unbalanced braces, trailing commas, wrong types), is not JSON at all (e.g. raw markdown or plain text), or has a structure that does not map to the Skill type's expected fields.

Common situations: Frontend sends skillCard as a form-encoded string with unescaped quotes breaking JSON; developer passes raw YAML frontmatter instead of JSON; Content-Type negotiation causes the form parser to deliver a truncated or double-encoded skillCard; a copy-paste from a markdown file is submitted where JSON was expected.

Related errors

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