alibaba/spring-ai-alibaba · error · IllegalArgumentException

SubAgent system prompt is required

Error message

SubAgent system prompt is required

What it means

SubAgentSpec's builder requires a non-blank systemPrompt in build(). The system prompt defines the sub-agent's behavior when it runs; without it the sub-agent would execute with no instructions. The builder throws IllegalArgumentException if systemPrompt is null or whitespace-only.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/SubAgentSpec.java:159

		public Builder interceptors(List<ModelInterceptor> interceptors) {
			this.interceptors = interceptors;
			return this;
		}

		public Builder enableLoopingLog(boolean enableLoopingLog) {
			this.enableLoopingLog = enableLoopingLog;
			return this;
		}

		public SubAgentSpec build() {
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("SubAgent name is required");
			}
			if (description == null || description.trim().isEmpty()) {
				throw new IllegalArgumentException("SubAgent description is required");
			}
			if (systemPrompt == null || systemPrompt.trim().isEmpty()) {
				throw new IllegalArgumentException("SubAgent system prompt is required");
			}
			return new SubAgentSpec(this);
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Provide the prompt via systemPrompt(...) before build().
2. If the prompt is loaded from a resource/config, assert it loaded non-empty before building and fail with the resource path in the message.
3. Use a shared constant or template for standard prompts to avoid blank placeholders.

Example fix

// before
SubAgentSpec spec = SubAgentSpec.builder()
    .name("billing-agent")
    .description("Handles billing questions")
    .systemPrompt(null)
    .build();
// after
SubAgentSpec spec = SubAgentSpec.builder()
    .name("billing-agent")
    .description("Handles billing questions")
    .systemPrompt("You are a billing support agent. Answer questions about invoices and payments.")
    .build();

String prompt = loadPrompt("billing-agent");
if (prompt == null || prompt.trim().isEmpty()) {
    throw new IllegalStateException("Prompt for billing-agent is empty or missing");
}

static boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }

try {
    spec = SubAgentSpec.builder().systemPrompt(prompt).build();
} catch (IllegalArgumentException e) {
    log.error("System prompt missing: {}", e.getMessage());
}

When it happens

Trigger: Calling SubAgentSpec.builder()...build() without calling systemPrompt(String), or passing null/""/blank text to systemPrompt().

Common situations: Loading prompts from external files/config at startup where the file is missing or empty; refactoring that moved the prompt to a placeholder not yet filled; quick prototypes that set only name and description.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• SubAgent name is required
• SubAgent description is required
• ChatModel must be provided for LLM routing agent
• LoopAgent must have a loopStrategy.
• Sub-agents must be provided

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