alibaba/spring-ai-alibaba · error

Fallback model {} failed: {}

Error message

Fallback model {} failed: {}

What it means

ModelFallbackInterceptor.interceptModel logs 'Fallback model {} failed' when fallback model i+1 also throws, records lastException, and continues to the next fallback. If all fallbacks are exhausted it throws RuntimeException('All models failed after N attempts', lastException). Each warning pinpoints which model in the chain failed and why.

Source

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

		catch (Exception e) {
			log.warn("Primary model failed: {}", e.getMessage());
			lastException = e;
		}

		// Try fallback models in sequence
		for (int i = 0; i < fallbackModels.size(); i++) {
			ChatModel fallbackModel = fallbackModels.get(i);
			try {
				log.info("Trying fallback model {} of {}", i + 1, fallbackModels.size());

				// Call the fallback model directly
				Prompt prompt = new Prompt(request.getMessages(), request.getOptions());
				var response = fallbackModel.call(prompt);

				return ModelResponse.of(response.getResult().getOutput());
			}
			catch (Exception e) {
				log.warn("Fallback model {} failed: {}", i + 1, e.getMessage());
				lastException = e;
			}
		}

		// All models failed
		throw new RuntimeException("All models failed after " + (fallbackModels.size() + 1) + " attempts", lastException);
	}

	@Override
	public String getName() {
		return "ModelFallback";
	}

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

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

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the logged message per fallback index to see whether failures share one root cause (e.g. same expired key)
2. Use fallback models from a different provider/region so outages don't correlate
3. Validate that request options are compatible with each fallback model
4. Catch the final RuntimeException at the application layer and degrade gracefully (cached response / user-facing error)
5. Fix the underlying auth/network issue for each model in the chain

Example fix

// before
.fallbackModels(List.of(dashScopeQwenMax, dashScopeQwenPlus)) // same provider, same outage
// after
.fallbackModels(List.of(dashScopeQwenMax, openAiGpt4oMini)) // independent providers

for (ChatModel m : allModels) { healthCheck(m); } // pre-flight auth/ping per model at startup

boolean fallbackUsable(ChatModel m, ModelRequest req) { return m != null && req.getMessages() != null && !req.getMessages().isEmpty(); }

try { return interceptor.interceptModel(request, chain); }
catch (RuntimeException e) { throw new ServiceException("Model chain unavailable", e.getCause()); }

When it happens

Trigger: Any exception from fallbackModel.call(prompt) during the fallback loop: network errors, auth failures, rate limits, invalid options, or context-length errors on each fallback model in turn.

Common situations: All configured models share the same broken API key or the same provider outage; fallback models are from the same region/service so a platform incident fails the whole chain; options (temperature, model name) invalid for the fallback model type.

Related errors

• Primary model failed: {}
• The model call returned an exception message: {}
• Model call failed (attempted {}/{}): {}
• Tool selection failed, using all tools: {}
• Path traversal not allowed:

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