alibaba/spring-ai-alibaba · warning · IllegalArgumentException

maxIterations must be > 0!

Error message

maxIterations must be > 0!

What it means

Deprecated CompiledGraph.setMaxIterations enforces a positive iteration cap, mirroring CompileConfig.recursionLimit. Passing <= 0 throws IllegalArgumentException. The method is deprecated for removal.

Solutions

1. Pass a positive value, e.g. setMaxIterations(25).
2. Migrate to CompileConfig.builder().recursionLimit(n).build() and compile the graph with it.
3. Remove setMaxIterations calls entirely; they are deprecated for removal.

Example fix

// before
compiledGraph.setMaxIterations(0);
// after
CompileConfig cfg = CompileConfig.builder().recursionLimit(25).build();
var compiled = graph.compile(cfg);

if (maxIterations <= 0) throw new IllegalArgumentException("maxIterations must be positive");

Integer safeMaxIterations(Integer v) { return (v == null || v <= 0) ? 25 : v; }

try { graph.setMaxIterations(n); } catch (IllegalArgumentException e) { log.warn("Invalid maxIterations {}; using recursionLimit instead", n); }

When it happens

Trigger: Calling setMaxIterations(0) or with a negative value — e.g. from the deprecated test path longSelfLoopShouldCompleteWithoutStackOverflow or legacy config code.

Common situations: Migrated code setting maxIterations from config that defaults to 0; copy-pasted builder code that used to allow 0 meaning 'unlimited'.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• At least one fallback model must be specified
• Condition keys cannot be null or empty
• Conditional flow requires at least one conditional agent…
• database cannot be null or blank
• dbType cannot be null or blank

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

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/CompiledGraph.java:541

	/**
	 * Package-private access to maxIterations for ReactiveNodeGenerator
	 */
	public int getMaxIterations() {
		return maxIterations;
	}

	/**
	 * Sets the maximum number of iterations for the graph execution.
	 *
	 * @param maxIterations the maximum number of iterations
	 * @throws IllegalArgumentException if maxIterations is less than or equal to 0
	 * @deprecated use CompileConfig.recursionLimit() instead
	 */
	@Deprecated(forRemoval = true)
	public void setMaxIterations(int maxIterations) {
		if (maxIterations <= 0) {
			throw new IllegalArgumentException("maxIterations must be > 0!");
		}
		this.maxIterations = maxIterations;
	}

	public GraphResponse<NodeOutput> invokeAndGetResponse(Map<String, Object> inputs, RunnableConfig config) {
		return graphResponseStream(inputs, config).last().block();
	}

	public GraphResponse<NodeOutput> invokeAndGetResponse(OverAllState state, RunnableConfig config) {
		return graphResponseStream(state, config).last().block();
	}

	public Flux<GraphResponse<NodeOutput>> graphResponseStream(Map<String, Object> inputs, RunnableConfig config) {
		return graphResponseStream(stateCreate(inputs), config);
	}

	public Flux<GraphResponse<NodeOutput>> graphResponseStream(OverAllState state, RunnableConfig config) {
		Objects.requireNonNull(config, "config cannot be null");

View on GitHub (pinned to f82da0b50f)