alibaba/spring-ai-alibaba · error · IllegalArgumentException

At least one fallback model must be specified

Error message

At least one fallback model must be specified

What it means

ModelFallbackInterceptor.Builder.build() refuses to construct an interceptor with an empty fallback model list, throwing IllegalArgumentException. The interceptor's whole purpose is falling back to alternatives, so at least one fallback ChatModel must be registered via addFallbackModel(...) or fallbackModels(...).

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/modelfallback/ModelFallbackInterceptor.java:123

		return "ModelFallback";
	}

	public static class Builder {
		private final List<ChatModel> fallbackModels = new ArrayList<>();

		public Builder addFallbackModel(ChatModel model) {
			this.fallbackModels.add(model);
			return this;
		}

		public Builder fallbackModels(List<ChatModel> models) {
			this.fallbackModels.addAll(models);
			return this;
		}

		public ModelFallbackInterceptor build() {
			if (fallbackModels.isEmpty()) {
				throw new IllegalArgumentException("At least one fallback model must be specified");
			}
			return new ModelFallbackInterceptor(this);
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call addFallbackModel(chatModel) at least once before build(), e.g. with a cheaper/smaller model than the primary.
2. If fallbacks may be legitimately absent, skip registering this interceptor instead of building it with an empty list.
3. Populate fallback models from configuration with a startup check that fails fast with a clear message if none are configured.

Example fix

// before
ModelFallbackInterceptor interceptor = ModelFallbackInterceptor.builder().build();
// after
ModelFallbackInterceptor interceptor = ModelFallbackInterceptor.builder()
    .addFallbackModel(fallbackChatModel)
    .build();

List<ChatModel> fallbacks = resolveFallbackModelsFromConfig();
if (fallbacks == null || fallbacks.isEmpty()) {
    throw new IllegalArgumentException("fallbackModels must contain at least one ChatModel before build()");
}
ModelFallbackInterceptor i = ModelFallbackInterceptor.builder().fallbackModels(fallbacks).build();

try {
    interceptor = ModelFallbackInterceptor.builder().build();
} catch (IllegalArgumentException e) {
    log.warn("No fallback models configured; skipping fallback interceptor");
    interceptor = null;
}

When it happens

Trigger: Calling ModelFallbackInterceptor.builder().build() (or after only empty-list calls) without any addFallbackModel(ChatModel) / fallbackModels(List<ChatModel>) invocation.

Common situations: Copy-pasting builder example code and deleting the addFallbackModel lines; conditionally adding fallback models where the condition was false at runtime; refactoring that moved fallback registration behind a feature flag that was disabled.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• maxConcurrency must be at least 1, but got:
• maxAttempts must be greater than or equal to 1
• initialDelay must be greater than or equal to 0.
• maxRetries must be >= 0
• maxTools must be > 0

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