What causes "invalid toolset name: %s" in googleapis/mcp-toolbox?

Rename the toolset to satisfy IsValidName (typically lowercase letters, digits, underscores/hyphens, non-empty)

invalid toolset name: %s

Error message

invalid toolset name: %s

What it means

Toolset.Initialize validates the toolset's name against IsValidName (naming rules: allowed characters/format). If the toolset name is invalid, Initialize returns this error. Toolset names must follow the library's naming convention, otherwise the toolset cannot be registered or served.

Source

Thrown at internal/tools/toolsets.go:96

		}
		toolsManifest[(*tool).GetName()] = m
	}
	return ToolsetManifest{ServerVersion: t.Manifest.ServerVersion, ToolsManifest: toolsManifest}, nil
}

func (t ToolsetConfig) Initialize(serverVersion string, toolsMap map[string]Tool) (Toolset, error) {
	// finish toolset setup
	// Check each declared tool name exists
	toolset := Toolset{
		ToolsetConfig: t,
		Tools:         make([]*Tool, 0, len(t.ToolNames)),
		Manifest: ToolsetManifest{
			ServerVersion: serverVersion,
		},
		toolNameSet: make(map[string]struct{}, len(t.ToolNames)),
	}
	if !IsValidName(toolset.Name) {
		return toolset, fmt.Errorf("invalid toolset name: %s", toolset.Name)
	}
	for _, toolName := range t.ToolNames {
		tool, ok := toolsMap[toolName]
		if !ok {
			return toolset, fmt.Errorf("tool does not exist: %s", toolName)
		}
		toolset.Tools = append(toolset.Tools, &tool)
		toolset.toolNameSet[toolName] = struct{}{}
	}
	return toolset, nil
}

var validName = regexp.MustCompile(`^[a-zA-Z0-9_-]*$`)

func IsValidName(s string) bool {
	return validName.MatchString(s)
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

Rename the toolset to satisfy IsValidName (typically lowercase letters, digits, underscores/hyphens, non-empty)
Check the toolset key in the YAML config for stray whitespace or special characters
Inspect IsValidName in internal/tools/toolsets.go for the exact accepted pattern
Quote and re-check the name in the error message for hidden characters

Example fix

// before (tools.yaml)
toolsets:
  "My Toolset":
    - run_query
// after
toolsets:
  my_toolset:
    - run_query

Defensive patterns

Strategy: validation

Validate before calling

validName := regexp.MustCompile(`^[a-z0-9_]+$`)
if !validName.MatchString(toolsetName) {
    return fmt.Errorf("toolset name %q is invalid; use lowercase letters, digits, underscores", toolsetName)
}

Try / catch

ts, err := t.Initialize(ctx)
if err != nil {
    if strings.Contains(err.Error(), "invalid toolset name") {
        return fmt.Errorf("rename toolset: %w", err)
    }
    return err
}

Prevention

Use lowercase snake_case or kebab-case for toolset keys
Trim whitespace around YAML keys
Check IsValidName's rules before inventing new naming styles

When it happens

Trigger: Calling Initialize (directly or via NewMockTool / toolset YAML parsing) with a Toolset whose Name fails IsValidName — e.g. empty name, spaces, uppercase, or special characters.

Common situations: Toolset key in YAML containing spaces or invalid characters; empty toolset name when constructing programmatically; kebab/snake case mismatch with validation rules.

Related errors

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