alibaba/spring-ai-alibaba · error · RuntimeException

Iteration Start node error (wraps caught exception)

Error message

Iteration Start node error (wraps caught exception)

What it means

IterationNode's start node (apply) extracts the element at the current index from the input array state. Any exception during that work (missing input array key, non-list input, JSON issues, index problems) is logged and rethrown wrapped in a RuntimeException. The message 'Iteration Start node error' is the log line; the thrown exception wraps the real cause, so the root cause is in getCause().

Source

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

				}
				else {
					// Read list and indexes from state
					list = (List<ElementInput>) state.value(this.inputArrayKey).orElseThrow();
					indexes = (List<Integer>) state.value(this.taskIndexListKey).orElseThrow();
				}

				if (indexes.isEmpty()) {
					return Map.of(this.outputStartIterationKey, false);
				}
				// Get the first element to process
				int index = indexes.get(0);
				indexes.remove(0);
				return Map.of(this.outputItemKey, list.get(index), this.outputStartIterationKey, true,
						this.taskIndexListKey, indexes, this.inputArrayKey, list);
			}
			catch (Exception e) {
				log.error("Iteration Start node error: {}", e.getMessage(), e);
				throw new RuntimeException(e);
			}
		}

		public static class Builder<ElementInput> {

			private String inputArrayJsonKey;

			private String inputArrayKey;

			private String outputItemKey;

			private String outputStartIterationKey;

			private String taskIndexListKey;

			public Start<ElementInput> build() {
				return new Start<>(inputArrayJsonKey, inputArrayKey, taskIndexListKey, outputItemKey,
						outputStartIterationKey);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Read the wrapped cause: e.getCause().getMessage() holds the real failure.
2. Verify the input array key exists in OverAllState before the iteration graph runs and holds a non-empty List.
3. Confirm the Builder's inputArrayJsonKey/output keys match the state keys used by upstream nodes.
4. Add a validation/checkpoint node ahead of the loop to guarantee array presence.

Example fix

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

Object arr = state.value(inputArrayJsonKey).orElse(null);
if (!(arr instanceof List<?> list) || list.isEmpty()) {
    throw new IllegalStateException("Iteration input '" + inputArrayJsonKey + "' must be a non-empty List");
}

boolean isValidIterationInput(OverAllState state, String key) {
    return state.value(key).map(v -> v instanceof List<?> l && !l.isEmpty()).orElse(false);
}

try {
    result = iterationStartNode.apply(state);
} catch (RuntimeException e) {
    Throwable cause = e.getCause();
    log.error("Iteration start failed: {}", cause == null ? e : cause);
    throw cause instanceof RuntimeException re ? re : e;
}

When it happens

Trigger: Running a state graph containing an IterationNode start node when the input array key is absent from state, the value is not a list/array, the input array is empty at index access, or the sub-state keys were configured incorrectly.

Common situations: Upstream node didn't produce the expected array before iteration began; key name mismatch between builder config (inputArrayJsonKey) and actual state keys; JSON input string malformed.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Iteration End 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/0725d830808cd1a3. Report an issue: GitHub.