alibaba/spring-ai-alibaba · error · IllegalArgumentException

LoopAgent must have a loopStrategy.

Error message

LoopAgent must have a loopStrategy.

What it means

LoopAgent needs a LoopStrategy to decide when to stop iterating; its builder's validate() (run from doBuild()) throws IllegalArgumentException if loopStrategy was never set. Without a strategy the loop would have no termination condition.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/LoopAgent.java:107

            this.subAgents = List.of(subAgent);
            return self();
        }

        @Override
        public LoopAgentBuilder subAgents(List<Agent> subAgents) {
            throw new UnsupportedOperationException("LoopAgent must have only one subAgent, please use subAgent() method.");
        }

        public LoopAgentBuilder loopStrategy(LoopStrategy loopStrategy) {
            this.loopStrategy = loopStrategy;
            return self();
        }

        @Override
        protected void validate() {
            super.validate();
            if (this.loopStrategy == null) {
                throw new IllegalArgumentException("LoopAgent must have a loopStrategy.");
            }
        }

        @Override
        public LoopAgent doBuild() {
            validate();
            return new LoopAgent(this);
        }
    }
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add loopStrategy(...) with an appropriate strategy (e.g., max iterations or a condition-based strategy) before build().
2. Check the library version's docs/examples — the required strategy API may have changed on upgrade.
3. If iteration count is the only need, use a simple max-iterations strategy; otherwise supply a condition-backed LoopStrategy.

Example fix

// before
LoopAgent agent = LoopAgent.builder()
    .subAgent(workerAgent)
    .build(); // throws: LoopAgent must have a loopStrategy.
// after
LoopAgent agent = LoopAgent.builder()
    .subAgent(workerAgent)
    .loopStrategy(LoopStrategy.maxIterations(5))
    .build();

Objects.requireNonNull(loopStrategy, "LoopAgent requires a LoopStrategy before build()");
LoopAgent agent = LoopAgent.builder().subAgent(a).loopStrategy(loopStrategy).build();

static boolean loopAgentReady(LoopStrategy s) { return s != null; }

try {
    agent = loopBuilder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("loopStrategy")) {
        log.error("LoopAgent built without loopStrategy; add loopStrategy(...)");
    }
}

When it happens

Trigger: Calling LoopAgent.builder()...build() without loopStrategy(...), or passing null to loopStrategy().

Common situations: Examples written before loopStrategy became mandatory after a version upgrade; building the loop conditionally where the strategy assignment branch is skipped; forgetting the strategy because subAgent() alone compiles fine.

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
• SubAgent system prompt is required
• ChatModel must be provided for LLM routing agent
• LoopAgent must have only one subAgent, please use subAgent()

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