{"record":{"id":"511dfb5291c9822a","repo":"alibaba/spring-ai-alibaba","slug":"no-toolcallback-found-for-tool-name","errorCode":null,"errorMessage":"No ToolCallback found for tool name: ","messagePattern":"No ToolCallback found for tool name: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java","lineNumber":264,"sourceCode":"\t\t}\n\t\t\n\t\tif (CollectionUtils.isNotEmpty(toolNames)) {\n\t\t\tfor (String toolName : toolNames) {\n\t\t\t\t// Skip the tool if it is already present in the request toolCallbacks.\n\t\t\t\t// That might happen if a tool is defined in the options\n\t\t\t\t// both as a ToolCallback and as a tool name.\n\t\t\t\tif (regularTools.stream().anyMatch(tool -> tool.getToolDefinition().name().equals(toolName))) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\t\n\t\t\t\tif (this.resolver == null) {\n\t\t\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\t\t\"ToolCallbackResolver is null; cannot resolve tool name: \" + toolName);\n\t\t\t\t}\n\t\t\t\tToolCallback toolCallback = this.resolver.resolve(toolName);\n\t\t\t\tif (toolCallback == null) {\n\t\t\t\t\tlogger.warn(POSSIBLE_LLM_TOOL_NAME_CHANGE_WARNING, toolName);\n\t\t\t\t\tthrow new IllegalStateException(\"No ToolCallback found for tool name: \" + toolName);\n\t\t\t\t}\n\t\t\t\tregularTools.add(toolCallback);\n\t\t\t}\n\t\t}\n\t\t\n\t\t// If regularTools is empty and resolver is provided, try to extract tools from resolver\n\t\tif (regularTools.isEmpty() && this.resolver != null) {\n\t\t\t// Check if resolver also implements ToolCallbackProvider\n\t\t\tif (this.resolver instanceof ToolCallbackProvider provider) {\n\t\t\t\tToolCallback[] resolverTools = provider.getToolCallbacks();\n\t\t\t\tif (resolverTools != null && resolverTools.length > 0) {\n\t\t\t\t\tregularTools.addAll(List.of(resolverTools));\n\t\t\t\t\tif (logger.isDebugEnabled()) {\n\t\t\t\t\t\tlogger.debug(\"Extracted {} tools from ToolCallbackResolver (ToolCallbackProvider)\",\n\t\t\t\t\t\t\t\tresolverTools.length);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java#L246-L282","documentation":"In gatherLocalTools, when a registered tool name cannot be resolved by the ToolCallbackResolver (resolver.resolve returns null) the builder logs a warning that the LLM may have changed the tool name and throws IllegalStateException. It means a referenced tool name matches no known ToolCallback.","triggerScenarios":"Passing a tool name string that no resolver bean provides, a typo in the tool name, or the tool bean not being registered/scanned when build() runs.","commonSituations":"Renaming an @Tool method without updating the agent's tool name list; tools defined in a module not on the classpath; resolution happening before the tool beans are registered.","solutions":["Fix the tool name string to exactly match the registered tool's name.","Verify the tool is registered: annotate the method with @Tool and ensure it's picked up by ToolCallbacks/method scanning.","Print resolver.resolve(name) for each configured name at startup to fail fast with a clear list of available tools.","If names come from an LLM/model output, sanitize or map them before registering."],"exampleFix":"// before\n.tools(\"get_weathr\")\n// after\n.tools(\"getWeather\")","handlingStrategy":"validation","validationCode":"for (String name : toolNames) {\n    if (resolver.resolve(name) == null)\n        throw new IllegalStateException(\"Unknown tool name before build(): \" + name);\n}","typeGuard":null,"tryCatchPattern":"try { agent = builder.build(); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"No ToolCallback found\")) { log.error(\"Registered tools: {}\", availableToolNames(resolver)); } throw e; }","preventionTips":["Keep tool names in constants shared between @Tool definitions and agent configs.","Add a startup check that resolves every configured tool name and lists valid alternatives on failure.","Re-check names after refactoring @Tool methods."],"tags":["tool-resolution","name-mismatch","illegal-state"],"backgroundTag":"resource-not-found","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"}