alibaba/nacos · error · IllegalArgumentException

Base directory cannot be blank

Error message

Base directory cannot be blank

What it means

Thrown by the three-argument SkillUtils.syncToLocal as an IllegalArgumentException when baseDir is blank (null, empty, or whitespace). The base directory is the root under which the skill directory is created; a blank value cannot be resolved into a valid filesystem path.

Source

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

     * @param skill the Skill object to sync
     * @param baseDir the base directory path where the skill directory will be created
     * @param strategy the strategy for handling existing directories
     * @throws IOException if file operations fail
     * @throws IllegalArgumentException if skill is null or skill name is blank
     * @throws FileAlreadyExistsException if directory exists and strategy is FAIL
     */
    public static void syncToLocal(Skill skill, String baseDir, ExistingDirectoryStrategy strategy)
        throws IOException {
        if (skill == null) {
            throw new IllegalArgumentException("Skill cannot be null");
        }
        
        if (StringUtils.isBlank(skill.getName())) {
            throw new IllegalArgumentException("Skill name cannot be blank");
        }
        
        if (StringUtils.isBlank(baseDir)) {
            throw new IllegalArgumentException("Base directory cannot be blank");
        }
        
        if (strategy == null) {
            strategy = ExistingDirectoryStrategy.OVERWRITE;
        }
        
        // Create skill directory path: {baseDir}/{skillName}
        Path basePath = Paths.get(baseDir);
        Path skillDir = basePath.resolve(skill.getName());
        
        // Delegate to core implementation
        syncToLocalCore(skill, skillDir, basePath, strategy);
    }
    
    /**
     * Sync Skill object to local directory with custom skill directory name.
     * Creates the skill directory structure, SKILL.md file, and resource files.
     * Uses OVERWRITE strategy by default.

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set the base directory configuration to an absolute, writable path (e.g. /var/nacos/skills).
2. Read the config with a required/default fallback so it is never blank.
3. Validate the resolved baseDir before the sync loop and fail fast with a clear config error.

Example fix

// before
String baseDir = System.getenv("SKILL_DIR"); // unset -> null
SkillUtils.syncToLocal(skill, baseDir, OVERWRITE); // throws

// after
String baseDir = System.getenv("SKILL_DIR");
if (StringUtils.isBlank(baseDir)) {
    baseDir = "/var/nacos/skills";
}
SkillUtils.syncToLocal(skill, baseDir, OVERWRITE); // ok

if (StringUtils.isBlank(baseDir)) {
    throw new IllegalStateException("Skill base directory is not configured (skill.baseDir)");
}
SkillUtils.syncToLocal(skill, baseDir, strategy);

static boolean isBaseDirConfigured(String baseDir) {
    return !StringUtils.isBlank(baseDir);
}

When it happens

Trigger: Calling syncToLocal(skill, null, strategy) or syncToLocal(skill, "", strategy). Common when a configuration property for the skills root directory was not set or resolved to empty.

Common situations: The 'nacos.ai.skill.base-dir' (or equivalent) config key was missing from the environment; a system property placeholder (${skill.dir}) was never substituted; the directory was read from an empty environment variable.

Related errors

• Invalid ZIP data: too short ({length} bytes)
• Invalid ZIP data: missing ZIP magic header (PK\x03\x04)
• Skill directory name 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/952b8d0259bfef99. Report an issue: GitHub.