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-download-object rejects a statically configured bucket that is an empty string. Either give a concrete bucket name or omit the field so a bucket parameter is injected for callers.

Source

Thrown at internal/tools/cloudstorage/cloudstoragedownloadobject/cloudstoragedownloadobject.go:79

	Annotations      *tools.ToolAnnotations `yaml:"annotations,omitempty"`
	Bucket           *string                `yaml:"bucket,omitempty"`
	DestinationDir   *string                `yaml:"destination_dir,omitempty"`
	Overwrite        *bool                  `yaml:"overwrite,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)
	}
	if cfg.DestinationDir != nil {
		if *cfg.DestinationDir == "" {
			return nil, fmt.Errorf("destination_dir cannot be empty for tool %q", cfg.Name)
		}
		if _, err := cloudstoragecommon.ValidateLocalPath(*cfg.DestinationDir); err != nil {
			return nil, fmt.Errorf("destination_dir is invalid for tool %q: %w", cfg.Name, err)
		}
	}

	objectParam := parameters.NewStringParameter(objectKey, "Full object name (path) within the bucket, e.g. 'path/to/file.txt'.")
	destinationDesc := "Absolute local filesystem path where the object will be written. Relative paths and paths containing '..' are rejected."
	if cfg.DestinationDir != nil {
		destinationDesc = "Relative path under the configured destination_dir where the object will be written. Absolute paths and paths that escape destination_dir are rejected."
	}
	allParameters := parameters.Parameters{}
	if cfg.Bucket == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(bucketKey, "Name of the Cloud Storage bucket containing the object."))

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Provide a valid bucket name in the bucket field
2. Remove the bucket field to make it a runtime parameter instead
3. Ensure the env var referenced in YAML is set in the process environment

Example fix

// before
bucket: "${GCS_BUCKET}"   # GCS_BUCKET unset => ""
// after
bucket: my-actual-bucket   # or remove the key to require it per-call

if b, ok := toolCfg["bucket"]; ok && b == "" {
    return errors.New("bucket must be a real name or omitted")
}

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

When it happens

Trigger: bucket: "" in the tool config, commonly from an unexpanded/empty environment variable like ${GCS_BUCKET} in tools.yaml.

Common situations: Missing env var at server start; CI pipelines not passing secrets; leftover bucket: key with no value after editing.

Related errors

• invalid source for %q tool: source %q is not a compatible ty
• description is required for tool %q
• bucket cannot be empty for tool %q
• invalid source for %q tool: source %q is not a compatible ty
• description is required for tool %q

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