googleapis/mcp-toolbox · error

unable to initialize group %q: %w

Error message

unable to initialize group %q: %w

What it means

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.

Source

Thrown at internal/server/server.go:384

			} else if cfg.IgnoreUnknownTools {
				l.WarnContext(ctx, fmt.Sprintf("Skipping missing tool %q in group %q", tn, name))
			} else {
				// Keep it so that Initialize returns the expected error
				filteredToolNames = append(filteredToolNames, tn)
			}
		}
		gc.ToolNames = filteredToolNames

		g, err := func() (group.Group, error) {
			_, span := instrumentation.Tracer.Start(
				ctx,
				"toolbox/server/group/init",
				trace.WithAttributes(attribute.String("group.name", name)),
			)
			defer span.End()
			g, err := gc.Initialize(toolsMap, promptsMap)
			if err != nil {
				return group.Group{}, fmt.Errorf("unable to initialize group %q: %w", name, err)
			}
			return g, nil
		}()
		if err != nil {
			return nil, err
		}
		groupsMap[name] = g
	}
	groupNames := make([]string, 0, len(groupsMap))
	for name := range groupsMap {
		if name == "" {
			groupNames = append(groupNames, "default")
		} else {
			groupNames = append(groupNames, name)
		}
	}
	l.InfoContext(ctx, fmt.Sprintf("Initialized %d groups: %s", len(groupsMap), strings.Join(groupNames, ", ")))

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Fix the group's tools/prompts list so every name matches a defined tool or prompt.
2. Set `ignoreUnknown: true` (IgnoreUnknownTools) if missing entries should be skipped with a warning instead of failing startup.
3. Resolve any preceding tool initialization failure — groups are validated after tools, so an earlier error often causes this one.
4. Note the default (nameless) group is auto-seeded with all tools; only named groups need explicit lists.

Example fix

// before
groupConfigs:
  my_group:
    description: My tools
    toolNames:
      - search_user  # does not exist

// after
groupConfigs:
  my_group:
    description: My tools
    toolNames:
      - search_users

defined := map[string]bool{}
for n := range cfg.ToolConfigs { defined[n] = true }
for n := range cfg.PromptConfigs { defined[n] = true }
for gname, gc := range cfg.GroupConfigs {
    for _, tn := range append(gc.ToolNames, gc.PromptNames...) {
        if !defined[tn] {
            return fmt.Errorf("group %q references undefined %q", gname, tn)
        }
    }
}

if _, err := server.NewServer(ctx, cfg); err != nil {
    var gname string
    if n, e := fmt.Sscanf(err.Error(), "unable to initialize group %q", &gname); n == 1 && e == nil {
        log.Printf("check group %q tool/prompt names", gname)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unable to initialize logger: %w
• invalid log level
• unable to initialize tool %q: %w
• unable to retrieve source %q for tool %q
• unable to initialize http log: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/1466e79a12342cfa. Report an issue: GitHub.