alibaba/spring-ai-alibaba · error · IllegalArgumentException

Config folder does not exist:

Error message

Config folder does not exist: 

What it means

ConfigAgentWatcher.watch(Path agentDirPath, ChangeCallback callback) throws IllegalArgumentException when the given path is not an existing directory (Files.isDirectory returns false). The watcher only supports watching real directories of YAML agent configs. The path may be missing, be a regular file, or be unreadable such that it doesn't present as a directory.

Source

Thrown at spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/loader/ConfigAgentWatcher.java:98

		}
		catch (InterruptedException e) {
			fileWatcher.shutdownNow();
			Thread.currentThread().interrupt();
		}
		started = false;
		logger.info("ConfigAgentWatcher stopped.");
	}

	/**
	 * Adds a folder to be watched for changes to any YAML files within it.
	 *
	 * @param agentDirPath The path to the agent configuration directory
	 * @param callback The callback to invoke when changes are detected
	 * @throws IllegalArgumentException if the folder doesn't exist
	 */
	void watch(Path agentDirPath, ChangeCallback callback) {
		if (!Files.isDirectory(agentDirPath)) {
			throw new IllegalArgumentException("Config folder does not exist: " + agentDirPath);
		}

		watchedFolders.put(agentDirPath, callback);

		// Scan and track all YAML files in the directory
		Map<Path, Long> yamlFiles = scanYamlFiles(agentDirPath);
		watchedYamlFiles.put(agentDirPath, yamlFiles);

		logger.debug("Now watching {} YAML files in agent folder: {}", yamlFiles.size(), agentDirPath);
	}

	/**
	 * Scans a directory recursively for all YAML files and returns their last modified times.
	 *
	 * @param agentDirPath The directory to scan recursively
	 * @return A map of YAML file paths to their last modified times
	 */
	private Map<Path, Long> scanYamlFiles(Path agentDirPath) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Create the directory before watching: Files.createDirectories(agentDirPath)
2. Use an absolute path or verify the process working directory so the relative path resolves correctly
3. Check the configured path points to a directory, not a YAML file (pass the parent dir instead)
4. In containers/k8s, verify the config volume is mounted at the expected path

Example fix

// before
watcher.watch(Path.of("config/agents"), callback); // fails if dir absent
// after
Path dir = Path.of("config/agents").toAbsolutePath();
Files.createDirectories(dir);
watcher.watch(dir, callback);

Path dir = agentDirPath == null ? null : agentDirPath.toAbsolutePath();
if (dir == null || !Files.isDirectory(dir)) {
    throw new IllegalArgumentException("Agent config dir must exist and be a directory: " + dir);
}

try {
    watcher.watch(dir, callback);
} catch (IllegalArgumentException e) {
    logger.error("Config dir invalid: {}", e.getMessage());
    Files.createDirectories(dir);
    watcher.watch(dir, callback);
}

When it happens

Trigger: Calling watch() with a path that does not exist, points to a file instead of a directory, uses a wrong relative path (resolved against the wrong working directory), or references a deleted/moved config folder.

Common situations: Hardcoded path like ./config/agents that doesn't exist in the deployment environment; running the app from a different working directory so relative paths resolve differently; container image missing the config directory; typo in the configured agent dir path.

Related errors

• Strategy type '' is already registered
• Strategy factory cannot be null
• No strategy registered for type:
• Graph name cannot be null or empty
• Tool not found with id: <id>

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/886371a7ab082bf5. Report an issue: GitHub.