alibaba/spring-ai-alibaba · error · IllegalArgumentException

Unknown JumpTo value: . Valid values are: tool, model, end

Error message

Unknown JumpTo value: . Valid values are: tool, model, end

What it means

JumpTo.fromString throws IllegalArgumentException when the string matches none of the enum constants. Valid values are tool, model, end (case-insensitive); the message includes the offending value and valid options.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/hook/JumpTo.java:65

	 * @param value the string value to convert
	 * @return the corresponding JumpTo enum instance
	 * @throws IllegalArgumentException if the value does not match any enum constant
	 */
	@JsonCreator
	public static JumpTo fromString(String value) {
		if (value == null) {
			throw new IllegalArgumentException("JumpTo value cannot be null");
		}

		// Try case-insensitive matching first
		for (JumpTo jumpTo : values()) {
			if (jumpTo.name().equalsIgnoreCase(value)) {
				return jumpTo;
			}
		}

		// If no match found, throw exception with helpful message
		throw new IllegalArgumentException(
			"Unknown JumpTo value: " + value + ". Valid values are: tool, model, end");
	}

	/**
	 * Converts a string to a JumpTo enum instance, returning null if the value is null or invalid.
	 * This is a safe version that doesn't throw exceptions.
	 * 
	 * @param value the string value to convert
	 * @return the corresponding JumpTo enum instance, or null if value is null or invalid
	 */
	public static JumpTo fromStringOrNull(String value) {
		if (value == null || value.trim().isEmpty()) {
			return null;
		}

		try {
			return fromString(value);
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Use one of the valid values: tool, model, end (case-insensitive)
2. Use fromStringOrNull or wrap in try-catch to handle unknown values gracefully
3. Normalize/validate the string against JumpTo values() before converting

Example fix

// before
JumpTo jump = JumpTo.fromString("finish");
// after
JumpTo jump = JumpTo.fromStringOrNull(input); // null handled explicitly

boolean valid = value != null && java.util.Arrays.stream(JumpTo.values()).anyMatch(j -> j.name().equalsIgnoreCase(value));

static JumpTo safeJump(String v) { return JumpTo.fromStringOrNull(v); }

JumpTo jump;
try {
    jump = JumpTo.fromString(value);
} catch (IllegalArgumentException e) {
    log.warn("Invalid jump target: {}", value);
    jump = JumpTo.END;
}

When it happens

Trigger: Calling JumpTo.fromString with a misspelled or unsupported value (e.g. "ToolCall", "finish", "exit"), or deserializing untrusted JSON into a JumpTo field via the @JsonCreator.

Common situations: Typos in hook configuration; LLM-generated or user-supplied JSON with an invalid jump target; version change where an old constant was removed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• JumpTo value cannot be null
• unsupported document type: ${documentType}
• Unknown experiment status code: ${code}
• Unknown dataset status code:
• Parallel flow requires root agent to be a FlowAgent

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