alibaba/spring-ai-alibaba · error · BizException

INVALID_PARAMS

INVALID_PARAMS

Error message

The parameters of the loop node do not conform to the array format.

What it means

IteratorExecuteProcessor.buildItemMap() deserializes each loop-node input parameter value into List<Object> using Jackson. If the value from the request context is not a JSON array, JsonProcessingException is caught and rethrown as BizException INVALID_PARAMS: the loop node's parameter doesn't conform to array format.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/workflow/processor/impl/IteratorExecuteProcessor.java:669

	 */
	private Map<String, List<Object>> buildItemMap(List<Node.InputParam> paramsArray, WorkflowContext context) {
		Map<String, List<Object>> params = Maps.newHashMap();

		if (Objects.isNull(paramsArray)) {
			return params;
		}
		ObjectMapper objectMapper = new ObjectMapper();
		paramsArray.forEach(param -> {
			String valueFromRequestContext = VariableUtils.getValueStringFromContext(param, context);
			// Convert JSON string to Map
			List<Object> list;
			try {
				list = objectMapper.readValue(valueFromRequestContext,
						new com.fasterxml.jackson.core.type.TypeReference<List<Object>>() {
						});
			}
			catch (JsonProcessingException e) {
				throw new BizException(ErrorCode.INVALID_PARAMS.toError("input_params",
						"The parameters of the loop node do not conform to the array format."));
			}
			params.put(param.getKey(), list);
		});
		return params;
	}

	/**
	 * Builds a map of variables for iteration
	 * @param paramsArray List of input parameters
	 * @param context The workflow context
	 * @return Map of variables for iteration
	 */
	private Map<String, Object> buildVariableMap(List<Node.InputParam> paramsArray, WorkflowContext context) {
		Map<String, Object> params = Maps.newHashMap();

		if (Objects.isNull(paramsArray)) {
			return params;

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect the actual value (log valueFromRequestContext) and ensure it is a JSON array like [1,2,3] or [{...},{...}]
2. Fix the upstream node's output to emit an array, or wrap it (e.g. code node: return [value];)
3. Correct the loop node's input configuration to reference the array field, not a scalar field
4. If the input is a literal, write it as valid JSON array syntax in the designer

Example fix

// before (loop input literal)
{"array": "a,b,c"}
// after
{"array": ["a", "b", "c"]}

Object v = context.get(paramKey);
boolean isArray = (v instanceof List<?>)
    || (v instanceof String s && s.trim().startsWith("[") && s.trim().endsWith("]"));
if (!isArray) throw new IllegalStateException("Loop input must be an array, got: " + v);

static boolean isJsonArrayValue(Object v) {
    if (v instanceof List<?>) return true;
    if (v instanceof String s) {
        String t = s.trim();
        return t.startsWith("[") && t.endsWith("]");
    }
    return false;
}

try {
    processor.execute(graph, node, context);
} catch (BizException e) {
    if (ErrorCode.INVALID_PARAMS.getCode().equals(e.getCode()) && e.getMessage().contains("array format")) {
        log.error("Loop node input is not an array; check upstream output/variable mapping");
    }
    throw e;
}

When it happens

Trigger: A loop/iterator node's input parameter (e.g. array-type input) resolves to a scalar, object, or malformed string instead of a JSON array when itemListMap calls buildItemMap.

Common situations: Upstream node outputs a single object instead of a list; a variable reference points at the wrong field; user typed a comma-separated string instead of configuring an array; JSON escaping issues in the configured literal.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• WORKFLOW_EXECUTE_ERROR
• WORKFLOW_CONFIG_INVALID
• unexcepted result
• value {${arrayKey}} is not an array!
• unknown component type: + componentType.getValue()

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