alibaba/spring-ai-alibaba · error · IllegalStateException

Skill path is required

Error message

Skill path is required

What it means

SkillMetadata.Builder.build() validates that skillPath (the file system location of the skill) is set and non-empty, throwing IllegalStateException otherwise. Without a path the library cannot locate or load the skill's files. This is a fail-fast invariant check during metadata construction.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/skills/SkillMetadata.java:172

		public Builder fullContent(String fullContent) {
			metadata.fullContent = fullContent;
			return this;
		}

		public Builder allowedTools(List<String> allowedTools) {
			metadata.allowedTools = allowedTools == null ? List.of() : List.copyOf(allowedTools);
			return this;
		}

		public SkillMetadata build() {
			if (metadata.name == null || metadata.name.isEmpty()) {
				throw new IllegalStateException("Skill name is required");
			}
			if (metadata.description == null || metadata.description.isEmpty()) {
				throw new IllegalStateException("Skill description is required");
			}
			if (metadata.skillPath == null || metadata.skillPath.isEmpty()) {
				throw new IllegalStateException("Skill path is required");
			}
			if (metadata.allowedTools == null) {
				metadata.allowedTools = List.of();
			}
			return metadata;
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .skillPath("/absolute/path/to/skill") on the builder before build()
2. If loading dynamically, resolve the SKILL.md file's absolute path and pass it in
3. Use the library's built-in loaders (ClasspathSkillRegistry / file registry) instead of hand-building metadata

Example fix

// before
SkillMetadata.builder().name("my-skill").description("does X").build();
// after
SkillMetadata.builder().name("my-skill").description("does X").skillPath("/skills/my-skill/SKILL.md").build();

if (skillPath == null || skillPath.isBlank()) throw new IllegalArgumentException("skillPath must be set before build()");

boolean hasPath(SkillMetadata m) { return m.getSkillPath() != null && !m.getSkillPath().isEmpty(); }

try { metadata = builder.build(); } catch (IllegalStateException e) { log.error("Skill metadata incomplete: {}", e.getMessage()); }

When it happens

Trigger: Building SkillMetadata programmatically via the builder without calling skillPath(...), or a loader that fails to resolve the skill directory before invoking build().

Common situations: Manually constructing SkillMetadata for a custom skill source and forgetting skillPath; a custom loader resolving SKILL.md without recording its parent directory.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Name must be provided
• Description must be provided
• AgentCard or AgentCardProvider must be provided
• Name must be provided
• ParallelAgent requires at least 2 sub-agents for parallel ex

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