{"record":{"id":"44e70b900ba8a21a","repo":"alibaba/spring-ai-alibaba","slug":"chatmodel-or-chatclient-must-be-provided-for-file","errorCode":null,"errorMessage":"chatModel or chatClient must be provided for file-based agent loading","messagePattern":"chatModel or chatClient must be provided for file-based agent loading","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/TaskToolsBuilder.java","lineNumber":231,"sourceCode":"\t\t}\n\t}\n\n\tprivate Map<String, ReactAgent> loadFromFiles() {\n\t\tif (agentDirectories.isEmpty() && agentResources.isEmpty()) {\n\t\t\treturn null;\n\t\t}\n\n\t\tAgentSpecReactAgentFactory factory = this.agentSpecFactory;\n\t\tif (factory == null) {\n\t\t\tAgentSpecReactAgentFactory.Builder fb = AgentSpecReactAgentFactory.builder();\n\t\t\tif (this.chatModel != null) {\n\t\t\t\tfb.chatModel(this.chatModel);\n\t\t\t}\n\t\t\telse if (this.chatClient != null) {\n\t\t\t\tfb.chatClient(this.chatClient);\n\t\t\t}\n\t\t\telse {\n\t\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\t\"chatModel or chatClient must be provided for file-based agent loading\");\n\t\t\t}\n\t\t\tif (!this.defaultTools.isEmpty()) {\n\t\t\t\tfb.defaultTools(this.defaultTools);\n\t\t\t}\n\t\t\tfactory = fb.build();\n\t\t}\n\n\t\tMap<String, ReactAgent> result = new HashMap<>();\n\t\tfor (String dir : agentDirectories) {\n\t\t\ttry {\n\t\t\t\tList<AgentSpec> specs = AgentSpecLoader.loadFromDirectory(dir);\n\t\t\t\tfor (AgentSpec spec : specs) {\n\t\t\t\t\tresult.put(spec.name(), factory.create(spec));\n\t\t\t\t}\n\t\t\t}\n\t\t\tcatch (IOException e) {\n\t\t\t\tthrow new RuntimeException(\"Failed to load agent specs from \" + dir, e);","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tools/task/TaskToolsBuilder.java#L213-L249","documentation":"TaskToolsBuilder.loadFromFiles builds an AgentFactory for file-based agent specs, which requires an LLM. When neither chatModel nor chatClient was set on the builder, an IllegalStateException is thrown because file-loaded specs cannot be instantiated without a model.","triggerScenarios":"Calling TaskToolsBuilder.fromFiles(...) (or loading agents from directories/resources) without having called .chatModel(...) or .chatClient(...) on the builder.","commonSituations":"Configuring file-based agents in code that only wires tools; refactoring away a ChatClient bean and forgetting to set it on the builder; creating the builder via a factory method that doesn't inherit the model.","solutions":["Call .chatModel(chatModel) on the TaskToolsBuilder before fromFiles/loadFromFiles.","Or call .chatClient(chatClient) if you have a composed ChatClient instead of a raw model.","Ensure a ChatModel/ChatClient bean is available (DashScope/OpenAI starter configured) and inject it into the builder."],"exampleFix":"// before\nTaskTools tools = TaskToolsBuilder.builder().build().loadFromFiles(List.of(Path.of(\"agents\")));\n// after\nTaskTools tools = TaskToolsBuilder.builder()\n    .chatModel(chatModel)\n    .build()\n    .loadFromFiles(List.of(Path.of(\"agents\")));","handlingStrategy":"validation","validationCode":"if (builder.getChatModel() == null && builder.getChatClient() == null) throw new IllegalStateException(\"Set chatModel or chatClient before file-based loading\");","typeGuard":"boolean canLoadFromFiles(TaskToolsBuilder b) { return b.getChatModel() != null || b.getChatClient() != null; }","tryCatchPattern":"try { tools = builder.loadFromFiles(dirs); } catch (IllegalStateException e) { log.error(\"Missing model for agent loading\", e); }","preventionTips":["Always wire chatModel/chatClient when constructing TaskToolsBuilder for file-based agents.","Inject the ChatModel bean in the component that builds TaskTools.","Add a unit test asserting fromFiles succeeds with the production builder config."],"tags":["configuration","agent-spec","chat-model"],"backgroundTag":"missing-required-argument","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}