alibaba/spring-ai-alibaba · error · IllegalArgumentException

Unsupported message type:

Error message

Unsupported message type: 

What it means

MessageDTOFactory.fromMessage converts Spring AI Message objects (AssistantMessage, UserMessage, ToolResponseMessage) into UI DTOs; AgentInstructionMessage and null are handled specially. Any other Message subtype has no DTO mapping, so an IllegalArgumentException naming the concrete class is thrown. It exists because Spring AI can produce message types (notably SystemMessage and custom subclasses) that the Studio transcript layer deliberately does not render.

Source

Thrown at spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/dto/messages/MessageDTO.java:92

				return null;
			}

			if (message instanceof AssistantMessage assistantMessage) {
				if (assistantMessage.hasToolCalls()) {
					return new ToolRequestMessageDTO(assistantMessage);
				}
				else {
					return new AssistantMessageDTO(assistantMessage);
				}
			}
			else if (message instanceof UserMessage) {
				return new UserMessageDTO((UserMessage) message);
			}
			else if (message instanceof ToolResponseMessage) {
				return new ToolResponseMessageDTO((ToolResponseMessage) message);
			}
			else {
				throw new IllegalArgumentException(
						"Unsupported message type: " + message.getClass().getName()
				);
			}
		}

		/**
		 * Convert InterruptionMetadata to ToolRequestMessageDTO.
		 * This is a specialized method for handling interruption metadata from agent execution.
		 */
		public static ToolRequestConfirmMessageDTO fromInterruptionMetadata(InterruptionMetadata interruptionMetadata) {
			if (interruptionMetadata == null) {
				return null;
			}
			return new ToolRequestConfirmMessageDTO(interruptionMetadata);
		}

		/**
		 * Convert DTO to Spring AI Message.

View on GitHub (pinned to f82da0b50f)

Solutions

1. Filter SystemMessage and other unmapped types out of the message list before calling fromMessage (skip or log them).
2. Extend the conversion switch to handle the concrete type reported in the exception message (e.g., add a branch mapping SystemMessage to null or a dedicated DTO).
3. Check your agent/graph construction: avoid injecting unmapped Message types into state keys that Studio serializes.
4. If a new Spring AI version added the type, file/apply an update to MessageDTOFactory's instanceof chain to cover it.

Example fix

// before
if (message instanceof AgentInstructionMessage) { return null; }
...
else { throw new IllegalArgumentException("Unsupported message type: " + ...); }

// after: tolerate system prompts by hiding them like instructions
if (message instanceof AgentInstructionMessage || message instanceof SystemMessage) {
    return null; // not rendered in the UI transcript
}

static boolean isConvertibleToDto(Message m) {
    return m instanceof AssistantMessage || m instanceof UserMessage || m instanceof ToolResponseMessage || m instanceof AgentInstructionMessage;
}

static MessageDTO safeFromMessage(Message m) {
    if (m instanceof AssistantMessage || m instanceof UserMessage || m instanceof ToolResponseMessage) {
        return MessageDTO.MessageDTOFactory.fromMessage(m);
    }
    return null; // skip SystemMessage and unknown subtypes
}

try {
    MessageDTO dto = MessageDTO.MessageDTOFactory.fromMessage(message);
} catch (IllegalArgumentException e) {
    log.warn("Skipping non-renderable message: {}", e.getMessage());
}

When it happens

Trigger: Calling MessageDTOFactory.fromMessage(message) with a Message that is none of AssistantMessage (with or without tool calls), UserMessage, ToolResponseMessage, or AgentInstructionMessage — most commonly a SystemMessage, or a custom Message subclass from a newer/patched Spring AI version, fed from graph state or history into the Studio thread/view pipeline.

Common situations: Graph state or chat history contains a SystemMessage (system prompts) that reaches the DTO conversion when rendering a thread; upgrading Spring AI introduces new Message implementations not yet mapped; custom framework code inserts its own Message subclass into state; tests feeding raw SystemMessage into the converter.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsupported DTO type:
• Tool message not supported
• ChatClient error
• Unsupported message type: {}
• Thread id is null

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