alibaba/spring-ai-alibaba · error · IllegalArgumentException

Invalid skill path

Error message

Invalid skill path: {}

What it means

AbstractSkillRegistry.normalizeSkillPath converts a skill path string to an absolute normalized Path; if the string is not a valid file-system path (contains NUL bytes or other illegal characters) Path.of throws InvalidPathException, which is rethrown as IllegalArgumentException with the offending path.

Solutions

1. Sanitize/validate the path string before passing it (reject control characters)
2. Pass paths obtained from SkillMetadata.getSkillPath() rather than free-form strings
3. Strip URI prefixes like 'file://' and convert to a plain filesystem path
4. On Windows, check the path against platform-illegal characters

Example fix

// before
registry.readSkillContentByPath("file://" + skillPath);
// after
registry.readSkillContentByPath(Paths.get(URI.create(uri)).toString());

if (p != null && (p.indexOf('\u0000') >= 0 || p.chars().anyMatch(Character::isISOControl))) throw new IllegalArgumentException("Path contains illegal characters");

boolean isParsablePath(String p) { try { if (p == null) return false; Path.of(p); return true; } catch (InvalidPathException e) { return false; } }

try { content = registry.readSkillContentByPath(p); } catch (IllegalArgumentException e) { log.warn("Invalid skill path '{}'", p); }

When it happens

Trigger: Calling readSkillContentByPath or findByPath with a string that cannot be parsed as a Path (illegal characters such as NUL, platform-invalid sequences).

Common situations: LLM-generated path arguments containing garbage characters; concatenation bugs injecting separators/NUL bytes; Windows-illegal characters used on Windows; passing a URI/URL string instead of a file path.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• AgentCard or AgentCardProvider must be provided
• AgentScope Model must be provided for AgentScope routing…
• AgentScope routing flow requires at least one sub-agent
• appName cannot be null or empty
• At least one fallback model must be specified

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

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/skills/registry/AbstractSkillRegistry.java:138

	@Override
	public String readSkillContentByPath(String skillPath) throws IOException {
		if (skillPath == null || skillPath.isBlank()) {
			throw new IllegalArgumentException("Skill path cannot be null or empty");
		}
		requireNormalizedSkillPath(skillPath);
		SkillMetadata skill = getByPath(skillPath)
				.orElseThrow(() -> new IllegalStateException("Skill not found: " + skillPath));
		return skill.loadFullContent();
	}

	protected abstract void loadSkillsToRegistry();

	protected static String normalizeSkillPath(String skillPath) {
		try {
			return Path.of(skillPath).toAbsolutePath().normalize().toString();
		}
		catch (InvalidPathException ex) {
			throw new IllegalArgumentException("Invalid skill path: " + skillPath, ex);
		}
	}

	protected static String requireNormalizedSkillPath(String skillPath) {
		if (skillPath == null || skillPath.isBlank()) {
			throw new IllegalArgumentException("Skill path cannot be null or empty");
		}
		return normalizeSkillPath(skillPath);
	}

	private Optional<SkillMetadata> findByPathInternal(String skillPath) {
		if (skillPath == null || skillPath.isBlank()) {
			return Optional.empty();
		}
		final String normalized;
		try {
			normalized = normalizeSkillPath(skillPath);
		}

View on GitHub (pinned to f82da0b50f)