alibaba/spring-ai-alibaba · error · IllegalStateException

Instruction is empty and shareState is false

Error message

Instruction is empty and shareState is false

What it means

getEffectiveInstruction resolves the prompt instruction sent to the remote A2A agent. If no instruction was configured and shareState is false (or shareState is true but state has no "messages"), there is nothing to send, so it throws this IllegalStateException.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/a2a/A2aNodeActionWithConfig.java:761

		root.put("id", id);
		root.put("jsonrpc", "2.0");
		root.put("method", "message/stream");
		root.put("params", params);

		try {
			return objectMapper.writeValueAsString(root);
		}
		catch (Exception e) {
			throw new IllegalStateException("Failed to build JSON-RPC streaming payload", e);
		}
	}

	private String getEffectiveInstruction(OverAllState state) {
		if (StringUtils.hasLength(this.instruction)) {
			PromptTemplate template = PromptTemplate.builder().template(this.instruction).build();
			return template.render(state.data());
		} else if (!shareState || (shareState && state.value("messages").isEmpty())) {
			throw new IllegalStateException("Instruction is empty and shareState is false");
		}
		return "";
	}

	/**
	 * Send the request to the remote A2A server and return the non-streaming response.
	 * @param agentCard Agent card (source for server URL/metadata)
	 * @param requestPayload JSON string payload built by buildSendMessageRequest
	 * @return Response body as string
	 */
	private String sendMessageToServer(AgentCardWrapper agentCard, String requestPayload) throws Exception {
		String baseUrl = resolveAgentBaseUrl(agentCard);
		System.out.println(baseUrl);
		System.out.println(requestPayload);
		if (baseUrl == null || baseUrl.isBlank()) {
			throw new IllegalStateException("AgentCard.url is empty");
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set an instruction on the A2A node builder: A2aNodeActionWithConfig.builder().instruction("...")...
2. Enable shareState so the node renders the prompt from the parent state's messages
3. Make sure an upstream node populates state key "messages" before the A2A node runs
4. Pre-check the graph wiring: the A2A node should not be the entry point when it depends on shared messages

Example fix

// before
A2aNodeActionWithConfig node = A2aNodeActionWithConfig.builder()
    .agentCard(card)
    .shareState(false)
    .build();
// after
A2aNodeActionWithConfig node = A2aNodeActionWithConfig.builder()
    .agentCard(card)
    .instruction("Summarize the user request")
    .shareState(false)
    .build();

boolean ready = StringUtils.hasLength(instruction)
    || (shareState && state.value("messages") != null && !state.value("messages").isEmpty());
if (!ready) throw new IllegalArgumentException("A2A node needs an instruction or shared messages");

When it happens

Trigger: Creating an A2aNodeActionWithConfig (via its builder) without calling instruction(...) while shareState is false; or with shareState true but the parent OverAllState has an empty/absent "messages" key at execution time.

Common situations: Forgetting to set the instruction on the A2A node builder; upstream node never wrote messages into shared state (wrong state key, upstream agent failed silently); wiring an A2A node as the first node in a graph with no user input yet.

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

• oss ak or sk should be set.
• oss bucket should be set.
• AppNotFound
• Unsupported vector store type:
• Unknown vector store type:

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