alibaba/nacos · error · IllegalArgumentException

Skill directory name cannot be blank

Error message

Skill directory name cannot be blank

What it means

Thrown by the four-argument SkillUtils.syncToLocal as an IllegalArgumentException when the resolved directory name is blank. The directory name is skillDirName if non-blank, otherwise skill.getName(); this error means BOTH were blank/null, so no directory name could be derived.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/skills/SkillUtils.java:362

     */
    public static void syncToLocal(Skill skill, String baseDir, String skillDirName,
        ExistingDirectoryStrategy strategy) throws IOException {
        if (skill == null) {
            throw new IllegalArgumentException("Skill cannot be null");
        }
        
        if (StringUtils.isBlank(baseDir)) {
            throw new IllegalArgumentException("Base directory cannot be blank");
        }
        
        if (strategy == null) {
            strategy = ExistingDirectoryStrategy.OVERWRITE;
        }
        
        // Use custom directory name or fall back to skill name
        String dirName = !StringUtils.isBlank(skillDirName) ? skillDirName : skill.getName();
        if (StringUtils.isBlank(dirName)) {
            throw new IllegalArgumentException("Skill directory name cannot be blank");
        }
        
        // Create skill directory path: {baseDir}/{skillDirName}
        Path basePath = Paths.get(baseDir);
        Path skillDir = basePath.resolve(dirName);
        
        // Delegate to core implementation
        syncToLocalCore(skill, skillDir, basePath, strategy);
    }
    
    /**
     * Core implementation for syncing Skill to local directory.
     * This method contains the common logic for all syncToLocal variants.
     *
     * @param skill the Skill object to sync
     * @param skillDir the target skill directory path
     * @param basePath the base directory path
     * @param strategy the strategy for handling existing directories

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass an explicit, non-blank skillDirName when the Skill's own name may be absent.
2. Ensure the Skill has a non-blank name (it is required for the resource identity).
3. Validate both skill.getName() and skillDirName before calling and reject the entry if both are blank.

Example fix

// before
Skill skill = new Skill(); // name not set
SkillUtils.syncToLocal(skill, baseDir, null, OVERWRITE); // throws

// after
Skill skill = new Skill();
skill.setName("my-skill");
SkillUtils.syncToLocal(skill, baseDir, null, OVERWRITE); // uses name, ok
// or pass explicit dir name:
SkillUtils.syncToLocal(skill, baseDir, "my-skill-dir", OVERWRITE); // ok

String dirName = !StringUtils.isBlank(skillDirName) ? skillDirName : skill.getName();
if (StringUtils.isBlank(dirName)) {
    throw new IllegalStateException("No directory name available (skillDirName blank and skill has no name)");
}
SkillUtils.syncToLocal(skill, baseDir, skillDirName, strategy);

static boolean hasUsableDirName(String skillDirName, Skill skill) {
    return !StringUtils.isBlank(skillDirName)
        || (skill != null && !StringUtils.isBlank(skill.getName()));
}

When it happens

Trigger: Calling syncToLocal(skill, baseDir, skillDirName, strategy) where skillDirName is null/blank AND skill.getName() is also null/blank. The skill object exists but has no name, and no explicit directory name was supplied.

Common situations: A Skill was deserialized with a missing name field and the caller did not pass a skillDirName; a custom directory name argument was computed from another empty field.

Related errors

• Invalid ZIP data: too short ({length} bytes)
• Invalid ZIP data: missing ZIP magic header (PK\x03\x04)
• Base directory cannot be blank
• Skill directory already exists: {skillDir}
• Absolute path not allowed: {path}

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