{"record":{"id":"857735de46926b5a","repo":"alibaba/spring-ai-alibaba","slug":"at-least-one-fallback-model-must-be-specified","errorCode":null,"errorMessage":"At least one fallback model must be specified","messagePattern":"At least one fallback model must be specified","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/modelfallback/ModelFallbackInterceptor.java","lineNumber":123,"sourceCode":"\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);\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic Builder fallbackModels(List<ChatModel> models) {\n\t\t\tthis.fallbackModels.addAll(models);\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic ModelFallbackInterceptor build() {\n\t\t\tif (fallbackModels.isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"At least one fallback model must be specified\");\n\t\t\t}\n\t\t\treturn new ModelFallbackInterceptor(this);\n\t\t}\n\t}\n}\n\n","sourceCodeStart":105,"sourceCodeEnd":130,"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#L105-L130","documentation":"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(...).","triggerScenarios":"Calling ModelFallbackInterceptor.builder().build() (or after only empty-list calls) without any addFallbackModel(ChatModel) / fallbackModels(List<ChatModel>) invocation.","commonSituations":"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.","solutions":["Call addFallbackModel(chatModel) at least once before build(), e.g. with a cheaper/smaller model than the primary.","If fallbacks may be legitimately absent, skip registering this interceptor instead of building it with an empty list.","Populate fallback models from configuration with a startup check that fails fast with a clear message if none are configured."],"exampleFix":"// before\nModelFallbackInterceptor interceptor = ModelFallbackInterceptor.builder().build();\n// after\nModelFallbackInterceptor interceptor = ModelFallbackInterceptor.builder()\n    .addFallbackModel(fallbackChatModel)\n    .build();","handlingStrategy":"validation","validationCode":"List<ChatModel> fallbacks = resolveFallbackModelsFromConfig();\nif (fallbacks == null || fallbacks.isEmpty()) {\n    throw new IllegalArgumentException(\"fallbackModels must contain at least one ChatModel before build()\");\n}\nModelFallbackInterceptor i = ModelFallbackInterceptor.builder().fallbackModels(fallbacks).build();","typeGuard":null,"tryCatchPattern":"try {\n    interceptor = ModelFallbackInterceptor.builder().build();\n} catch (IllegalArgumentException e) {\n    log.warn(\"No fallback models configured; skipping fallback interceptor\");\n    interceptor = null;\n}","preventionTips":["Always register at least one cheap fallback model (e.g. a mini/turbo variant) as a standard pattern.","Add a unit test asserting your agent's interceptor chain builds successfully.","Fail fast at startup: validate fallback configuration before registering interceptors."],"tags":["builder","validation","configuration","java"],"backgroundTag":"empty-required-field","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"}