alibaba/spring-ai-alibaba · error · IllegalArgumentException

JumpTo value cannot be null

Error message

JumpTo value cannot be null

What it means

JumpTo.fromString converts a string to the JumpTo enum (used by hooks to redirect control flow). It throws IllegalArgumentException when the input string is null, since null cannot match any enum constant.

Source

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

	@Override
	@JsonValue
	public String toString() {
		return name();
	}

	/**
	 * Converts a string to a JumpTo enum instance.
	 * Supports case-insensitive matching.
	 * Used for JSON deserialization via @JsonCreator annotation.
	 * 
	 * @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.
	 * 

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a non-null string ("tool", "model", or "end") to fromString
2. Use JumpTo.fromStringOrNull when the value may be null
3. Default the field to a valid value before serialization

Example fix

// before
JumpTo jump = JumpTo.fromString(hookResult.getJumpTo()); // may be null
// after
JumpTo jump = JumpTo.fromStringOrNull(hookResult.getJumpTo());

if (value == null) return null;
if (java.util.Arrays.stream(JumpTo.values()).noneMatch(j -> j.name().equalsIgnoreCase(value))) return null;

static JumpTo safeJump(String v) { return v == null ? null : JumpTo.fromStringOrNull(v); }

JumpTo jump;
try {
    jump = JumpTo.fromString(value);
} catch (IllegalArgumentException e) {
    jump = JumpTo.END; // default
}

When it happens

Trigger: Calling JumpTo.fromString(null) directly, or deserializing JSON where the jump target field is null/absent and a @JsonCreator maps it through fromString.

Common situations: Hook result object missing the jumpTo field; JSON payload without the field; passing a nullable variable without checking it first.

Related errors

• Unknown JumpTo value: . Valid values are: tool, model, end
• 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/7bea7afd814ab49d. Report an issue: GitHub.