alibaba/spring-ai-alibaba · error · RuntimeException

ChatClient error

Error message

ChatClient error

What it means

The generated LLM node code calls chatClient.prompt()...call().content() and throws RuntimeException("ChatClient error") when the model returns a null content. It signals the ChatClient call completed without producing usable text.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/workflow/sections/LLMNodeSection.java:114

						            memories = "This is the user's first request without context";
						        }
						        else {
						            memories = String.format("This is the history of previous requests:\\n %%s",
						                    state.value(memoryKey, List.of()).toString());
						        }

						        // call chatClient
						        int retryCount = Optional.ofNullable(maxRetryCount).orElse(1);
						        int retryInterval = Optional.ofNullable(retryIntervalMs).orElse(1000);
						        while (retryCount-- > 0) {
						            try {
						                // build messages
						                List<Message> messages = messageTemplates.stream()
						                    .map(messageTemplate -> messageTemplate.render(state))
						                    .toList();
						                String content = chatClient.prompt().system(memories).messages(messages).call().content();
						                if (content == null) {
						                    throw new RuntimeException("ChatClient error");
						                }
						                Map<String, Object> map = new HashMap<>(%s);
						                if (memoryKey != null) {
						                    map.put(memoryKey, content);
						                }
						                return map;
						            }
						            catch (Exception e) {
						                try {
						                    Thread.sleep(retryInterval);
						                } catch (InterruptedException ie) {
						                    Thread.currentThread().interrupt();
						                    break;
						                }
						            }
						        }

						        // error handling

View on GitHub (pinned to f82da0b50f)

Solutions

1. Verify the ChatModel/API key and model name configuration for the workspace
2. Check provider-side response (logs/observability) for empty completions and adjust maxTokens/prompt
3. Wrap the node with an error edge (errorNextNode) so failures route to an error branch instead of aborting

Example fix

// before
String content = chatClient.prompt().system(memories).messages(messages).call().content();
// after
String content = chatClient.prompt().system(memories).messages(messages)
    .call().content();
if (content == null || content.isBlank()) {
    content = ""; // or route to error node
}

if (chatModelConfig.getApiKey() == null || chatModelConfig.getApiKey().isBlank()) { throw new IllegalStateException("Model API key not configured"); }

null

try { String content = chatClient.prompt()...call().content(); } catch (RuntimeException e) { log.error("LLM call failed", e); routeToErrorNode(); }

When it happens

Trigger: At runtime of the generated workflow: the ChatClient call returns null content — typically empty/failed model completion, misconfigured model or API key, or the model returning only reasoning with no content.

Common situations: Missing or invalid DashScope/OpenAI API key; model name not available in the region; max-tokens set too low so response is empty; network issues returning empty body.

Understand the failure class

Background: "empty response", "returned no data", "empty embeddings": what HTTP 200-with-empty-body errors mean across libraries — this error's family across 36 libraries.

Related errors

• Tool message not supported
• ChatClient is required
• rerank response is null.
• Elastic search index name must be provided
• Param Not Support Object

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