spring-projects/spring-ai · error · IllegalArgumentException

Maximum of 8 skills per request. Provided:

Error message

Maximum of 8 skills per request. Provided: 

What it means

AnthropicSkillContainer's constructor enforces the Anthropic API limit of at most 8 skills per request and also requires the list to be non-null and non-empty. Passing more than 8 AnthropicSkillRecord entries throws IllegalArgumentException with the actual size appended to the message.

Source

Thrown at models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicSkillContainer.java:40

import java.util.Map;

import org.springframework.util.Assert;

/**
 * Container for Claude Skills in a chat completion request. Maximum of 8 skills per
 * request.
 *
 * @author Soby Chacko
 */
public class AnthropicSkillContainer {

	private final List<AnthropicSkillRecord> skills;

	public AnthropicSkillContainer(List<AnthropicSkillRecord> skills) {
		Assert.notNull(skills, "Skills list cannot be null");
		Assert.notEmpty(skills, "Skills list cannot be empty");
		if (skills.size() > 8) {
			throw new IllegalArgumentException("Maximum of 8 skills per request. Provided: " + skills.size());
		}
		this.skills = Collections.unmodifiableList(new ArrayList<>(skills));
	}

	public List<AnthropicSkillRecord> getSkills() {
		return this.skills;
	}

	/**
	 * Convert to a list of maps suitable for JSON serialization via
	 * {@code JsonValue.from(Map.of("skills", container.toSkillsList()))}.
	 * @return list of skill maps with type, skill_id, and version keys
	 */
	public List<Map<String, Object>> toSkillsList() {
		return this.skills.stream().map(AnthropicSkillRecord::toJsonMap).toList();
	}

	public static Builder builder() {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Reduce the list to at most 8 skills before constructing the container (prioritize the most relevant ones).
2. Split work into multiple requests, each with <= 8 skills, if all skills are genuinely needed.
3. Add an application-level guard or config validation that fails early with a clear message when more than 8 skills are configured.
4. Check for accidental duplicate skill registrations inflating the list size.

Example fix

// before
new AnthropicSkillContainer(allSkills); // allSkills.size() == 12
// after
new AnthropicSkillContainer(allSkills.stream().limit(8).toList());

if (skills == null || skills.isEmpty()) throw new IllegalArgumentException("At least one skill required");
if (skills.size() > 8) throw new IllegalArgumentException("Anthropic allows at most 8 skills, got " + skills.size());

try {
    container = new AnthropicSkillContainer(selectedSkills);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Maximum of 8 skills")) {
        container = new AnthropicSkillContainer(selectedSkills.subList(0, 8));
    } else throw e;
}

When it happens

Trigger: Creating new AnthropicSkillContainer(skillList) where skillList.size() > 8; programmatically accumulating skill records from configuration or discovery and passing the whole list in one request.

Common situations: Loading all skills from a directory or config and hitting the 8-skill API cap; aggregating per-team skill definitions without a global limit; test fixtures with many skills.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid filename for file '': null or blank
• Invalid filename for file '':
• Invalid filename for file '': absolute path ''
• Unsupported media type: . Supported types are: images (image
• Unsupported media data type: . Expected byte[] or String.

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/8f31a9d740abe37b. Report an issue: GitHub.