alibaba/spring-ai-alibaba · error · RuntimeException

Iteration End node error (wraps caught exception)

Error message

Iteration End node error (wraps caught exception)

What it means

IterationNode's end node (apply) appends the element result to the output list, serializes the accumulated list to JSON, and decides whether iteration should continue. Any exception in that step (JSON serialization failure, missing state keys, index bookkeeping errors) is logged and rethrown as a wrapping RuntimeException. The underlying reason is in the cause.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/node/IterationNode.java:257

				List<ElementOutput> outputList = new ArrayList<>(
						OBJECT_MAPPER.readValue(state.value(this.outputArrayJsonKey, String.class).orElse("[]"),
								new TypeReference<List<ElementOutput>>() {
								}));
				// Check if it's an empty iteration node (i.e. outputStartIterationKey is false)
				if (!state.value(this.outputStartIterationKey, Boolean.class).orElse(false)) {
					return Map.of(this.outputContinueIterationKey, false, this.outputArrayJsonKey,
							OBJECT_MAPPER.writeValueAsString(outputList));
				}
				List<Integer> indexes = (List<Integer>) state.value(this.taskIndexSetKey, List.class).orElseThrow();
				ElementOutput result = (ElementOutput) state.value(this.inputResultKey).orElseThrow();
				// Add subgraph node processing result to final result array
				outputList.add(result);
				return Map.of(this.outputArrayJsonKey, OBJECT_MAPPER.writeValueAsString(outputList),
						this.outputContinueIterationKey, !indexes.isEmpty());
			}
			catch (Exception e) {
				log.error("Iteration End node error: {}", e.getMessage(), e);
				throw new RuntimeException(e);
			}
		}

		public static class Builder<ElementInput, ElementOutput> {

			private String taskIndexListKey;

			private String inputResultKey;

			private String outputArrayKey;

			private String outputContinueIterationKey;

			private String outputStartIterationKey;

			private Builder() {
				this.taskIndexListKey = null;
				this.inputResultKey = null;

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect e.getCause() for the true error (often JsonProcessingException).
2. Ensure all loop-body outputs are JSON-serializable objects.
3. Confirm outputArrayJsonKey, outputContinueIterationKey and index keys are configured identically in start/end builders.
4. Validate that the subGraph end node writes the expected result key each iteration.

Example fix

// before
catch (Exception e) {
    log.error("Iteration End node error: {}", e.getMessage(), e);
    throw new RuntimeException(e);
}
// after
catch (Exception e) {
    log.error("Iteration End node error", e);
    throw new RuntimeException("Iteration End node failed", e);
}

Object result = state.value(iteratorResultKey).orElse(null);
if (result != null) objectMapper.writeValueAsString(result); // fail fast if unserializable

boolean isSerializableResult(Object o) {
    try { objectMapper.writeValueAsString(o); return true; } catch (JsonProcessingException e) { return false; }
}

try {
    result = iterationEndNode.apply(state);
} catch (RuntimeException e) {
    log.error("Iteration end failed, cause: {}", e.getCause(), e);
    throw e;
}

When it happens

Trigger: Running the iteration end node when outputArrayJsonKey state manipulation fails, OBJECT_MAPPER.writeValueAsString throws (unserializable element result), or the task-index list state is corrupted/missing.

Common situations: Loop body node returns values that cannot be JSON-serialized into the output array; key mismatch between start/end node builders; nested subgraph mutated the index keys unexpectedly.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Iteration Start node error (wraps caught exception)
• TOOL_EXECUTION_ERROR
• value {${arrayKey}} is not an array!
• 查询评估器关联的实验失败:
• 模型配置解析失败:

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