{"record":{"id":"ce6572d5e8a898d4","repo":"googleapis/mcp-toolbox","slug":"tool-q-not-found","errorCode":null,"errorMessage":"tool %q not found","messagePattern":"tool %q not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/internal/invoke/command.go","lineNumber":81,"sourceCode":"\tif err != nil {\n\t\treturn err\n\t}\n\n\t// Initialize Resources\n\tsourcesMap, authServicesMap, embeddingModelsMap, toolsMap, promptsMap, groupsMap, err := server.InitializeConfigs(ctx, opts.Cfg)\n\tif err != nil {\n\t\terrMsg := fmt.Errorf(\"failed to initialize resources: %w\", err)\n\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\treturn errMsg\n\t}\n\n\tprimitiveMgr := primitives.NewPrimitiveManager(sourcesMap, authServicesMap, embeddingModelsMap, toolsMap, promptsMap, groupsMap)\n\n\t// Execute Tool\n\ttoolName := args[0]\n\ttool, ok := primitiveMgr.GetTool(toolName)\n\tif !ok {\n\t\terrMsg := fmt.Errorf(\"tool %q not found\", toolName)\n\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\treturn errMsg\n\t}\n\n\tsrcName := tool.GetSourceName()\n\tvar src sources.Source\n\tif srcName != \"\" {\n\t\tsrc, ok = primitiveMgr.GetSource(srcName)\n\t\tif !ok {\n\t\t\terrMsg := fmt.Errorf(\"unable to retrieve source for tool %s\", toolName)\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\t}\n\n\terr = tool.ValidateSource(src)\n\tif err != nil {\n\t\topts.Logger.ErrorContext(ctx, err.Error())","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/internal/invoke/command.go#L63-L99","documentation":"After initializing resources, runInvoke looks up the requested tool by name in the PrimitiveManager. If no tool with that name is registered, the command fails with this error. It means the first positional argument did not match any tool defined in the loaded config(s).","triggerScenarios":"Running `toolbox invoke <name>` where <name> is absent from the tools file and prebuilt configs: a typo, a tool defined under a different kind, the wrong --tools-file/--prebuilt flag, or the tool was removed/renamed in a newer config version.","commonSituations":"Typos in the tool name, invoking a prebuilt tool whose config wasn't selected via --prebuilt, renamed tools after upgrading toolbox, using the service/group name instead of the tool name.","solutions":["Run `toolbox tools list` (or start the server and curl /api/tools) to see the exact registered tool names and copy one verbatim","Check that --tools-file / --prebuilt flags point to the config actually containing the tool","Verify the tool name spelling and casing (names are case-sensitive)","After a toolbox upgrade, regenerate or update the tools file to the new schema/tool names"],"exampleFix":"// before\ntoolbox invoke --tools-file tools.yaml list_users  # tool is actually named list-users\ntoolbox invoke list_users\n// error: tool \"list_users\" not found\n// after\ntoolbox invoke list-users","handlingStrategy":"validation","validationCode":"out, _ := exec.Command(\"toolbox\", \"tools\", \"list\", \"--tools-file\", cfgPath).Output()\nif !strings.Contains(string(out), toolName) {\n    return fmt.Errorf(\"tool %q is not registered in %s\", toolName, cfgPath)\n}","typeGuard":null,"tryCatchPattern":"if err := runInvoke(ctx, opts); err != nil {\n    if strings.Contains(err.Error(), \"not found\") && strings.Contains(err.Error(), \"tool\") {\n        return fmt.Errorf(\"unknown tool: %w; run 'toolbox tools list' for valid names\", err)\n    }\n    return err\n}","preventionTips":["List registered tools (`toolbox tools list` or GET /api/tools) and copy names verbatim","Tool names are case-sensitive — match casing exactly","Ensure the correct --tools-file/--prebuilt flag selects the config containing the tool","Check release notes for renamed tools when upgrading"],"tags":["go","cli","config","tool-lookup"],"backgroundTag":"tool-not-found","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}