googleapis/mcp-toolbox · error

bucket cannot be empty for tool %q

Error message

bucket cannot be empty for tool %q

What it means

Initialize for cloudstorage-delete-object rejects a bucket field that is explicitly provided but set to an empty string. A static bucket must be a non-empty bucket name; if you want the bucket supplied at invocation time, omit the field entirely so a bucket parameter is added.

Source

Thrown at internal/tools/cloudstorage/cloudstoragedeleteobject/cloudstoragedeleteobject.go:74

	tools.ConfigBase `yaml:",inline"`
	Type             string                 `yaml:"type" validate:"required"`
	Source           string                 `yaml:"source" validate:"required"`
	Annotations      *tools.ToolAnnotations `yaml:"annotations,omitempty"`
	Bucket           *string                `yaml:"bucket,omitempty"`
}

var _ tools.ToolConfig = Config{}

func (cfg Config) ToolConfigType() string {
	return resourceType
}

func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
	if cfg.Description == "" {
		return nil, fmt.Errorf("description is required for tool %q", cfg.Name)
	}
	if cfg.Bucket != nil && *cfg.Bucket == "" {
		return nil, fmt.Errorf("bucket cannot be empty for tool %q", cfg.Name)
	}

	objectParam := parameters.NewStringParameter(objectKey, "Full object name (path) within the bucket, e.g. 'path/to/file.txt'.")
	allParameters := parameters.Parameters{}
	if cfg.Bucket == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(bucketKey, "Name of the Cloud Storage bucket containing the object to delete."))
	}
	allParameters = append(allParameters, objectParam)

	return Tool{
		BaseTool: tools.NewBaseTool(
			cfg,
			tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewDestructiveAnnotations),
			tools.Manifest{Description: cfg.Description, Parameters: allParameters.Manifest(), AuthRequired: cfg.AuthRequired},
			allParameters,
		),
	}, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Set a real bucket name for the bucket field
2. If the bucket should come from the LLM/caller at runtime, remove the bucket field entirely (a bucket parameter is then added automatically)
3. Verify the environment variable used in the YAML is exported in the server process

Example fix

// before
tools:
  delete-object:
    kind: cloudstorage-delete-object
    source: my-gcs
    description: Delete object
    bucket: ""
// after
tools:
  delete-object:
    kind: cloudstorage-delete-object
    source: my-gcs
    description: Delete object
    bucket: my-bucket-name

if bucket, ok := toolCfg["bucket"]; ok && bucket == "" {
    return errors.New("bucket must be non-empty or omitted")
}

if err := startToolbox(); err != nil {
    if strings.Contains(err.Error(), "bucket cannot be empty") {
        // check env expansion / YAML value
    }
    log.Fatal(err)
}

When it happens

Trigger: tools.yaml contains bucket: "" (e.g. an environment-variable interpolation like ${BUCKET_NAME} that expanded to empty) for a cloudstorage-delete-object tool.

Common situations: Env var not set at startup so ${BUCKET_NAME} renders empty; hand-edited YAML leaving bucket: with no value; templating tools stripping values.

Related errors

• description is required for tool %q
• description is required for tool %q
• destination_dir cannot be empty for tool %q
• description is required for tool %q
• description is required for tool %q

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