googleapis/mcp-toolbox · error

bucket cannot be empty for tool %q

Error message

bucket cannot be empty for tool %q

What it means

Thrown by cloudstorage-list-objects Config.Initialize when the config supplies a 'bucket' value that is an empty string. Bucket is an optional field; when set it must point to a real GCS bucket, so an explicit empty string is treated as a config error rather than 'use bucket parameter at call time'.

Source

Thrown at internal/tools/cloudstorage/cloudstoragelistobjects/cloudstoragelistobjects.go:84

	Annotations      *tools.ToolAnnotations `yaml:"annotations,omitempty"`
	Bucket           *string                `yaml:"bucket,omitempty"`
	Prefix           *string                `yaml:"prefix,omitempty"`
	Delimiter        *string                `yaml:"delimiter,omitempty"`
}

// validate interface
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)
	}

	maxResultsParam := parameters.NewIntParameter(maxResultsKey, "Maximum number of objects to return per page. A value of 0 uses the API default (1000); negative values and values above 1000 are rejected.", parameters.WithIntDefault(0))
	pageTokenParam := parameters.NewStringParameter(pageTokenKey, "A previously-returned page token for retrieving the next page of results.", parameters.WithStringDefault(""))
	allParameters := parameters.Parameters{}
	if cfg.Bucket == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(bucketKey, "Name of the Cloud Storage bucket to list objects from."))
	}
	if cfg.Prefix == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(prefixKey, "Filter results to objects whose names begin with this prefix.", parameters.WithStringDefault("")))
	}
	if cfg.Delimiter == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(delimiterKey, "Delimiter used to group object names (typically '/'). When set, common prefixes are returned as 'prefixes'.", parameters.WithStringDefault("")))
	}
	allParameters = append(allParameters, maxResultsParam, pageTokenParam)

	return Tool{
		BaseTool: tools.NewBaseTool(

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Remove the 'bucket' field entirely from the tool config so buckets are supplied per invocation
2. Set the bucket to a valid non-empty GCS bucket name (e.g. `bucket: my-bucket`)
3. Fix the environment variable/secret so it expands to the actual bucket name instead of empty

Example fix

// before
tools:
  list-objects:
    kind: cloudstorage-list-objects
    source: my-gcs
    description: List objects
    bucket: ""
// after
tools:
  list-objects:
    kind: cloudstorage-list-objects
    source: my-gcs
    description: List objects
    bucket: my-bucket

// Pre-check: bucket must be either absent or non-empty
if b, present := toolCfg["bucket"]; present && strings.TrimSpace(fmt.Sprint(b)) == "" {
    return fmt.Errorf("bucket is set but empty; remove it or provide a real bucket name")
}

When it happens

Trigger: tools.yaml contains `bucket: ""` (or a template/variable that expanded to empty) for a cloudstorage-list-objects tool while the field is non-nil.

Common situations: Environment variable for the bucket name not set, causing empty expansion; quoting an empty YAML value intending to leave the field unset; copying a config and clearing the bucket to force per-call bucket supply.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

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