{"record":{"id":"1466e79a12342cfa","repo":"googleapis/mcp-toolbox","slug":"unable-to-initialize-group-q-w","errorCode":null,"errorMessage":"unable to initialize group %q: %w","messagePattern":"unable to initialize group %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/server/server.go","lineNumber":384,"sourceCode":"\t\t\t} else if cfg.IgnoreUnknownTools {\n\t\t\t\tl.WarnContext(ctx, fmt.Sprintf(\"Skipping missing tool %q in group %q\", tn, name))\n\t\t\t} else {\n\t\t\t\t// Keep it so that Initialize returns the expected error\n\t\t\t\tfilteredToolNames = append(filteredToolNames, tn)\n\t\t\t}\n\t\t}\n\t\tgc.ToolNames = filteredToolNames\n\n\t\tg, err := func() (group.Group, error) {\n\t\t\t_, span := instrumentation.Tracer.Start(\n\t\t\t\tctx,\n\t\t\t\t\"toolbox/server/group/init\",\n\t\t\t\ttrace.WithAttributes(attribute.String(\"group.name\", name)),\n\t\t\t)\n\t\t\tdefer span.End()\n\t\t\tg, err := gc.Initialize(toolsMap, promptsMap)\n\t\t\tif err != nil {\n\t\t\t\treturn group.Group{}, fmt.Errorf(\"unable to initialize group %q: %w\", name, err)\n\t\t\t}\n\t\t\treturn g, nil\n\t\t}()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tgroupsMap[name] = g\n\t}\n\tgroupNames := make([]string, 0, len(groupsMap))\n\tfor name := range groupsMap {\n\t\tif name == \"\" {\n\t\t\tgroupNames = append(groupNames, \"default\")\n\t\t} else {\n\t\t\tgroupNames = append(groupNames, name)\n\t\t}\n\t}\n\tl.InfoContext(ctx, fmt.Sprintf(\"Initialized %d groups: %s\", len(groupsMap), strings.Join(groupNames, \", \")))\n","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/server.go#L366-L402","documentation":"initializeGroups calls GroupConfig.Initialize(toolsMap, promptsMap) for every group (toolset). A group is invalid when it references tool or prompt names that are not present in the initialized maps (and were not suppressed or ignored via IgnoreUnknownTools). The error wraps the group name to locate the offending collection entry.","triggerScenarios":"A `group`/`toolsets` entry in the config lists a tool name that failed to initialize, was removed, is misspelled, or lists a prompt name that does not exist, while cfg.IgnoreUnknownTools is false.","commonSituations":"Deleting or renaming a tool but leaving the old name in a toolset, referencing a prompt in a promptset that was never defined, or a tool that failed earlier (e.g. error 392/393) cascading into group validation.","solutions":["Fix the group's tools/prompts list so every name matches a defined tool or prompt.","Set `ignoreUnknown: true` (IgnoreUnknownTools) if missing entries should be skipped with a warning instead of failing startup.","Resolve any preceding tool initialization failure — groups are validated after tools, so an earlier error often causes this one.","Note the default (nameless) group is auto-seeded with all tools; only named groups need explicit lists."],"exampleFix":"// before\ngroupConfigs:\n  my_group:\n    description: My tools\n    toolNames:\n      - search_user  # does not exist\n\n// after\ngroupConfigs:\n  my_group:\n    description: My tools\n    toolNames:\n      - search_users","handlingStrategy":"validation","validationCode":"defined := map[string]bool{}\nfor n := range cfg.ToolConfigs { defined[n] = true }\nfor n := range cfg.PromptConfigs { defined[n] = true }\nfor gname, gc := range cfg.GroupConfigs {\n    for _, tn := range append(gc.ToolNames, gc.PromptNames...) {\n        if !defined[tn] {\n            return fmt.Errorf(\"group %q references undefined %q\", gname, tn)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"if _, err := server.NewServer(ctx, cfg); err != nil {\n    var gname string\n    if n, e := fmt.Sscanf(err.Error(), \"unable to initialize group %q\", &gname); n == 1 && e == nil {\n        log.Printf(\"check group %q tool/prompt names\", gname)\n    }\n    return err\n}","preventionTips":["Regenerate group tool lists from defined tools rather than typing names by hand.","Set ignoreUnknown: true for optional tools so a rename degrades gracefully.","When renaming a tool, search the whole config for the old name.","CI-lint groups against defined tools/prompts before deploy."],"tags":["go","groups","toolsets","configuration"],"backgroundTag":"missing-referenced-tool","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"}