{"record":{"id":"d3adb32f650e49ed","repo":"alibaba/spring-ai-alibaba","slug":"fallback-model-failed","errorCode":null,"errorMessage":"Fallback model {} failed: {}","messagePattern":"Fallback model (.+?) failed: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/modelfallback/ModelFallbackInterceptor.java","lineNumber":94,"sourceCode":"\t\tcatch (Exception e) {\n\t\t\tlog.warn(\"Primary model failed: {}\", e.getMessage());\n\t\t\tlastException = e;\n\t\t}\n\n\t\t// Try fallback models in sequence\n\t\tfor (int i = 0; i < fallbackModels.size(); i++) {\n\t\t\tChatModel fallbackModel = fallbackModels.get(i);\n\t\t\ttry {\n\t\t\t\tlog.info(\"Trying fallback model {} of {}\", i + 1, fallbackModels.size());\n\n\t\t\t\t// Call the fallback model directly\n\t\t\t\tPrompt prompt = new Prompt(request.getMessages(), request.getOptions());\n\t\t\t\tvar response = fallbackModel.call(prompt);\n\n\t\t\t\treturn ModelResponse.of(response.getResult().getOutput());\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tlog.warn(\"Fallback model {} failed: {}\", i + 1, e.getMessage());\n\t\t\t\tlastException = e;\n\t\t\t}\n\t\t}\n\n\t\t// All models failed\n\t\tthrow new RuntimeException(\"All models failed after \" + (fallbackModels.size() + 1) + \" attempts\", lastException);\n\t}\n\n\t@Override\n\tpublic String getName() {\n\t\treturn \"ModelFallback\";\n\t}\n\n\tpublic static class Builder {\n\t\tprivate final List<ChatModel> fallbackModels = new ArrayList<>();\n\n\t\tpublic Builder addFallbackModel(ChatModel model) {\n\t\t\tthis.fallbackModels.add(model);","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/modelfallback/ModelFallbackInterceptor.java#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the logged message per fallback index to see whether failures share one root cause (e.g. same expired key)","Use fallback models from a different provider/region so outages don't correlate","Validate that request options are compatible with each fallback model","Catch the final RuntimeException at the application layer and degrade gracefully (cached response / user-facing error)","Fix the underlying auth/network issue for each model in the chain"],"exampleFix":"// before\n.fallbackModels(List.of(dashScopeQwenMax, dashScopeQwenPlus)) // same provider, same outage\n// after\n.fallbackModels(List.of(dashScopeQwenMax, openAiGpt4oMini)) // independent providers","handlingStrategy":"fallback","validationCode":"for (ChatModel m : allModels) { healthCheck(m); } // pre-flight auth/ping per model at startup","typeGuard":"boolean fallbackUsable(ChatModel m, ModelRequest req) { return m != null && req.getMessages() != null && !req.getMessages().isEmpty(); }","tryCatchPattern":"try { return interceptor.interceptModel(request, chain); }\ncatch (RuntimeException e) { throw new ServiceException(\"Model chain unavailable\", e.getCause()); }","preventionTips":["Diversify fallback providers/regions","Ensure request options are valid for every model in the chain","Set per-model timeouts so one slow model doesn't exhaust the budget","Log and monitor per-index fallback failures to spot shared root causes"],"tags":["model","fallback","interceptor","resilience"],"backgroundTag":"upstream-api-error","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}