alibaba/spring-ai-alibaba · error · BizException

WORKFLOW_CONFIG_INVALID

WORKFLOW_CONFIG_INVALID

Error message

${nodeName} vision param is not File or List<File>

What it means

LLMExecuteProcessor.constructUserMessage() builds a Spring AI UserMessage with media attachments when a vision parameter is configured. If the vision parameter value is neither a File nor a List<File> (so no media list could be built), it throws BizException WORKFLOW_CONFIG_INVALID naming the node.

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/LLMExecuteProcessor.java:308

				else if (value instanceof File) {
					Media media = constructMedia(value);
					if (media == null) {
						return new UserMessage(userPrompt);
					}
					return UserMessage.builder().text(userPrompt).media(media).build();
				}
				else if (value instanceof List) {
					List<Media> mediaList = ((List<?>) value).stream()
						.map(this::constructMedia)
						.filter(Objects::nonNull)
						.collect(Collectors.toList());
					if (CollectionUtils.isEmpty(mediaList)) {
						return new UserMessage(userPrompt);
					}
					return UserMessage.builder().text(userPrompt).media(mediaList).build();
				}
				else {
					throw new BizException(ErrorCode.WORKFLOW_CONFIG_INVALID
						.toError(node.getName() + " vision param is not File or List<File>"));
				}
			}
		}
		return new UserMessage(userPrompt);
	}

	/**
	 * Constructs a media object from the provided value
	 * @param value The value to convert into media
	 * @return A Media object if conversion is successful, null otherwise
	 */
	private Media constructMedia(Object value) {
		if (value == null) {
			return null;
		}
		if (!(value instanceof File)) {
			throw new BizException(ErrorCode.WORKFLOW_CONFIG_INVALID.toError("object is not File"));

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure the value bound to the vision param is a File or List<File>; add a conversion node or use the file-reference variable type
2. If you have URLs, wrap them into the framework's File/media type expected by the LLM node
3. Check the upstream node's output type and select the correct output field in the vision parameter mapping

Example fix

// before (vision param bound to)
String imageUrl = "https://.../img.png";
// after
List<File> images = List.of(new File("/tmp/img.png")); // or file variable from upload node

Object vision = context.get(visionParam);
if (!(vision instanceof File) && !(vision instanceof List<?>)) {
    throw new IllegalStateException(node.getName() + " vision param must be File or List<File>");
}

static boolean isValidVisionParam(Object v) {
    if (v instanceof File) return true;
    if (v instanceof List<?> l) return l.isEmpty() || l.get(0) instanceof File;
    return false;
}

try {
    processor.execute(graph, node, context);
} catch (BizException e) {
    if (ErrorCode.WORKFLOW_CONFIG_INVALID.getCode().equals(e.getCode()) && e.getMessage().endsWith("vision param is not File or List<File>")) {
        log.error("Fix vision input mapping on node: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: An LLM node's vision/image input variable resolves to a type other than File or List<File> — e.g. a plain String URL, Map, or JSON object — while constructing the user message in innerExecute.

Common situations: Upstream node outputs image URLs as strings instead of File objects; user wired a text variable into the vision input; file-reference format changed between framework versions.

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

• INVALID_PARAMS
• unexcepted result
• value {${arrayKey}} is not an array!
• unknown component type: + componentType.getValue()
• extra tool param should be map

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