googleapis/mcp-toolbox · error

--name is required unless --group or --toolset is set, or ex

Error message

--name is required unless --group or --toolset is set, or exactly one --prebuilt config is provided

What it means

resolveSkillName validates that a skill name can be derived from the CLI inputs: an explicit --name, a --group, a --toolset, or exactly one --prebuilt config. If none of these can supply a name (empty name, no group/toolset, and zero or multiple prebuilt configs), the command refuses to proceed with this usage error.

Source

Thrown at cmd/internal/skills/command.go:264

// resolveSkillName returns the explicit --name when set. Otherwise, in the
// single-skill modes it defaults to the --group or --toolset name, and for
// prebuilt generation it defaults to the config name when exactly one
// --prebuilt config is given. Any other case requires --name.
func resolveSkillName(name, group, toolset string, prebuiltConfigs []string) (string, error) {
	if name != "" {
		return name, nil
	}
	if group != "" {
		return group, nil
	}
	if toolset != "" {
		return toolset, nil
	}
	if len(prebuiltConfigs) == 1 {
		return strings.ReplaceAll(prebuiltConfigs[0], "/", "-"), nil
	}
	return "", fmt.Errorf("--name is required unless --group or --toolset is set, or exactly one --prebuilt config is provided")
}

func (c *skillsCmd) collectContents(ctx context.Context, opts *internal.ToolboxOptions) (map[string]skillContent, error) {
	// Initialize tools and groups only; skills generation does not need live
	// sources, auth services, or embedding models.
	toolsMap, groupsMap, err := server.InitializeOfflineConfigs(ctx, opts.Cfg)
	if err != nil {
		return nil, fmt.Errorf("failed to initialize resources: %w", err)
	}

	return c.buildSkillContents(toolsMap, groupsMap)
}

// buildSkillContents maps each skill name to the tools and description it should
// be generated with. In group mode, a group's own description takes precedence
// over the --description flag, which acts as a fallback.
func (c *skillsCmd) buildSkillContents(toolsMap map[string]tools.Tool, groupsMap map[string]group.Group) (map[string]skillContent, error) {
	primitiveMgr := primitives.NewPrimitiveManager(nil, nil, nil, toolsMap, nil, groupsMap)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add an explicit --name flag (e.g. --name my-skill)
2. If using --prebuilt, pass exactly one config, or keep multiple but add --name
3. Verify you passed --group or --toolset (check spelling) if you intended name derivation from them
4. Run `toolbox skills --help` to review the accepted flag combinations

Example fix

// before
toolbox skills --prebuilt postgres --prebuilt mysql
// error: --name is required...
// after
toolbox skills --name my-db-skill --prebuilt postgres --prebuilt mysql

# Validate flag combination before invoking
toolbox skills --name my-skill --prebuilt postgres  # OK
toolbox skills --prebuilt postgres                   # OK (single prebuilt)
toolbox skills --prebuilt postgres --prebuilt mysql  # FAILS: needs --name
toolbox skills --tools list_tables                   # FAILS: needs --name, --group, or --toolset

try {
  execSync("toolbox skills --prebuilt postgres --prebuilt mysql", { stdio: "inherit" });
} catch (e) {
  if (String(e.stderr).includes("--name is required")) {
    console.error("Add --name or reduce to one --prebuilt config");
  } else { throw e; }
}

When it happens

Trigger: Running `toolbox skills` with no --name and none of: a --group, a --toolset, or exactly one --prebuilt flag — e.g. --name omitted with --tools selected, or multiple --prebuilt configs given without --name.

Common situations: Forgetting --name when picking individual tools with --tools; passing two or more --prebuilt configs expecting auto-naming; misspelling --group/--toolset so the flag parses as empty; upgrading from a single-prebuilt workflow to multiple prebuilts without adding --name.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• log format must be one of "standard", or "json"
• log level must be one of "debug", "info", "warn", or "error"
• failed to initialize resources: %w
• tool %q not found
• unable to retrieve source for tool %s

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