conductor-oss/conductor · error · IllegalArgumentException

Skill manifest name '{manifestName}' does not match package

Error message

Skill manifest name '{manifestName}' does not match package SKILL.md name '{name}'

What it means

Thrown by register() when the 'name' field in the JSON manifest part does not match the 'name' parsed from the SKILL.md YAML frontmatter inside the uploaded zip package. The manifest is the @RequestPart("manifest") and the package SKILL.md is the source of truth; the two must agree. This guards against accidental name drift between the registration metadata and the actual skill payload.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/SkillRegistryService.java:154

        }
    }

    public synchronized SkillDetail register(String manifestJson, MultipartFile packageFile) {
        requireSkillStorage();
        if (packageFile == null || packageFile.isEmpty()) {
            throw new IllegalArgumentException("Skill package is required");
        }

        Map<String, Object> manifest = parseManifest(manifestJson);
        byte[] bytes = readPackage(packageFile);
        String checksum = sha256Hex(bytes);

        ParsedSkillPackage parsed = parseSkillPackage(bytes, manifest);
        String name = parsed.name();
        Map<String, Object> rawConfig = parsed.rawConfig();
        String manifestName = stringValue(manifest.get("name"));
        if (manifestName != null && !manifestName.isBlank() && !manifestName.equals(name)) {
            throw new IllegalArgumentException(
                    "Skill manifest name '"
                            + manifestName
                            + "' does not match package SKILL.md name '"
                            + name
                            + "'");
        }

        String version = stringValue(manifest.get("version"));
        if (version == null || version.isBlank()) {
            version = checksum.substring(0, 12);
        }
        validateVersion(version);
        pinRegisteredCrossSkillRefs(rawConfig);

        long now = Instant.now().toEpochMilli();

        Optional<SkillDetail> existingOpt = metadataDao.find(name, version);
        if (existingOpt.isPresent()) {

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Make the manifest 'name' exactly equal to the SKILL.md frontmatter 'name' (case-sensitive, no surrounding whitespace).
Omit the 'name' field from the manifest entirely — if manifestName is null/blank the check is skipped and SKILL.md wins.
Rebuild the zip so SKILL.md and manifest stay in sync, then re-upload.

Example fix

// before: manifest.json has "name":"translate" but SKILL.md has name: translator
// after — align both:
---
# SKILL.md frontmatter
name: translate
---
// manifest.json
{"name":"translate","version":"1.0.0"}

Defensive patterns

Strategy: validation

Validate before calling

// Before register(), assert manifest name matches SKILL.md frontmatter name
String manifestName = (String) new ObjectMapper().readValue(manifestJson, Map.class).get("name");
if (manifestName != null && !manifestName.isBlank()) {
    String pkgName = readSkillMdFrontmatterName(packageZipBytes); // parse SKILL.md frontmatter
    if (!manifestName.equals(pkgName)) {
        throw new IllegalStateException("manifest name " + manifestName + " != SKILL.md name " + pkgName);
    }
}

Type guard

// Java: confirm manifest carries a usable name or is intentionally omitted
static boolean manifestNameConsistentOrAbsent(Map<String,Object> manifest, String skillMdName) {
    Object n = manifest.get("name");
    return n == null || n.toString().isBlank() || n.toString().equals(skillMdName);
}

Try / catch

try { skillRegistryService.register(manifest, pkg); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("does not match")) { /* align names, re-upload */ }
    else throw e;
}

Prevention

Single-source the skill name from one config and inject it into both the manifest JSON and the SKILL.md frontmatter at build time.
In CI, parse SKILL.md frontmatter and assert it equals the manifest name before publishing.

When it happens

Trigger: POST /api/skills/register with a manifest body containing "name":"my-skill" while the zip's SKILL.md frontmatter declares name: my-skill-v2. Also fires when the manifest name has trailing whitespace or a typo relative to SKILL.md. Triggered only when manifestName is non-blank AND differs from parsed.name().

Common situations: Renaming a skill by editing only the manifest JSON without rebuilding the zip; CI pipelines that template the manifest separately from the SKILL.md; copy-pasting a manifest between skills and forgetting to update one of the two name fields.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/8e6d4050f0245c6e. Report an issue: GitHub.