DEV Community

Solon Framework
Solon Framework

Posted on

Debugging ReActAgent 'Tool Message Order' Error in Solon AI

#agents #ai #debugging #llm

If you're using Solon's ReActAgent to build multi-step AI agents, you might hit a frustrating error after the first tool call succeeds:

Error code:400, message:{"code":20015,"message":"Value error, after tool message, next must be user or assistant message","data":null}
Enter fullscreen mode Exit fullscreen mode

This isn't a hypothetical scenario — it happened to a real user (GitHub issue #121) who upgraded from Solon AI v3.9.3 to v3.10.7. The agent worked fine for the first round of reasoning and tool execution, then failed consistently on subsequent steps.

What Was Happening

The user had a ReActAgent configured with multiple tools, including one that queries dietary data by date. When the agent needed to call the same tool multiple times (e.g., "query my diet for the past 3 days"), each tool call created a message in the conversation history. The problem was in the message ordering — after a tool response, the next message needed to be a user or assistant message, but the framework was producing a malformed sequence.

Here's the error in context:

WARN: ReActAgent [react_agent] retry 1/3 due to: 
Error code:400, message:{"code":20015,"message":"Value error, after tool message, next must be user or assistant message","data":null}
Enter fullscreen mode Exit fullscreen mode

The error repeated 3 times until the agent gave up with:

ReActAgent [react_agent] finished, abnormal:true, finalAnswer: 抱歉，暂时无法使用模型服务
Enter fullscreen mode Exit fullscreen mode

The Root Cause

The issue was in the ReActAgent's message handling logic in v3.10.7. When the agent invoked a tool and received a response, the subsequent message construction didn't properly align with the LLM API's expected message format. The model (DeepSeek-V4-Pro in this case) enforced stricter message ordering rules — specifically, after a tool role message, the next message must be user or assistant, not another tool message.

The user's configuration:

ReActAgent robot = ReActAgent.of(chatModel)
    .role("You are a super agent...")
    .planningMode(true)
    .instruction(Pmp.CHAT_INSTRUCTION)
    .defaultToolContextPut("token", token)
    .sessionWindowSize(10)
    .modelOptions(o -> o
        .temperature(0.1F)
        .optionSet("enable_thinking", false))
    .build();
Enter fullscreen mode Exit fullscreen mode

The Fix

The issue was resolved in Solon AI v4.0.0, which was released shortly after the bug report. The v4.0.0 release included a complete overhaul of the message formatting logic to properly handle multi-tool-call sequences.

Workaround for v3.10.x

If you're stuck on v3.10.x and can't upgrade immediately, you can reduce the likelihood of this error by:

  1. Lowering maxSteps — fewer sequential tool calls reduce the chance of message ordering issues
  2. Adding autoRethink(true) — this tells the agent to reflect and reformat when it hits the message limit 
ReActAgent robot = ReActAgent.of(chatModel)
    .planningMode(true)
    .autoRethink(true)  // Added: self-reflection when max turns approach
    // ... rest of config
    .build();
Enter fullscreen mode Exit fullscreen mode

The Real Fix: Upgrade to v4.0.0+

The user was advised to upgrade to v4.0.0, which fixed the underlying issue. The v4.0.0 release notes include:

ReActAgent message format fix — Proper handling of tool call sequences to comply with LLM API message ordering requirements.

Key Takeaways

  1. Always check the message format — Different LLM providers have different rules about message ordering. DeepSeek, OpenAI, and Anthropic all enforce slightly different constraints.

  2. Upgrade to the latest version — Solon AI v4.0.0 fixed this specific issue. If you're on v3.10.x and using ReActAgent with multiple tool calls, upgrading is recommended.

  3. Use autoRethink for resilience — Even with the fix, autoRethink(true) provides a safety net when the agent's reasoning path gets complex.

  4. Test with your specific model — The error manifested with DeepSeek-V4-Pro specifically. Different models may trigger different edge cases.

This article is based on a real GitHub issue: opensolon/solon-ai#121. Solon AI v4.0.0 fixed this issue. Official docs: solon.noear.org/article/1456

Top comments (0)