googleapis/mcp-toolbox · error

failed to create bucket %q in project %q: %w

Error message

failed to create bucket %q in project %q: %w

What it means

BucketHandle.Create failed while creating the bucket in the given project. The wrapped GCS error explains the cause: most often the (globally unique) bucket name is already taken, the name is invalid, or the caller lacks storage.buckets.create permission.

Source

Thrown at internal/sources/cloudstorage/cloudstorage.go:328

// CreateBucket creates a Cloud Storage bucket and returns its freshly-read
// metadata. When project is empty, the source's configured project is used.
// When location is empty, Cloud Storage applies its service default.
func (s *Source) CreateBucket(ctx context.Context, bucket, project, location string, uniformBucketLevelAccess bool) (map[string]any, error) {
	if err := s.validateBucket(bucket); err != nil {
		return nil, err
	}
	if project == "" {
		project = s.Project
	}
	attrs := &storage.BucketAttrs{Location: location}
	if uniformBucketLevelAccess {
		attrs.UniformBucketLevelAccess = storage.UniformBucketLevelAccess{Enabled: true}
	}

	bkt := s.client.Bucket(bucket)
	if err := bkt.Create(ctx, project, attrs); err != nil {
		return nil, fmt.Errorf("failed to create bucket %q in project %q: %w", bucket, project, err)
	}

	createdAttrs, err := bkt.Attrs(ctx)
	if err != nil {
		return nil, fmt.Errorf("failed to get metadata for created bucket %q: %w", bucket, err)
	}
	return map[string]any{
		"bucket":   bucket,
		"created":  true,
		"metadata": createdAttrs,
	}, nil
}

// GetBucketMetadata returns raw bucket metadata from the Cloud Storage client.
func (s *Source) GetBucketMetadata(ctx context.Context, bucket string) (*storage.BucketAttrs, error) {
	if err := s.validateBucket(bucket); err != nil {
		return nil, err
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check for 409 AlreadyExists: if the bucket exists and is yours, skip creation and proceed to Attrs/usage.
2. Generate a globally unique, lowercase, hyphenated name (e.g. project-scoped with random suffix).
3. Grant the service account roles/storage.admin (or storage.buckets.create) on the project and enable the Cloud Storage API.
4. Validate the requested location/storage class against org policy before retrying.

Example fix

// before
source.CreateBucket(ctx, "my-test-bucket", "my-project", nil, "US", "STANDARD", false) // name taken
// after
name := fmt.Sprintf("my-project-bucket-%s", strings.ToLower(uniqSuffix()))
source.CreateBucket(ctx, name, "my-project", nil, "US", "STANDARD", false)

// bucket names: 3-63 lowercase letters, digits, hyphens, dots
var bucketNameRe = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$`)
if !bucketNameRe.MatchString(bucket) {
    return fmt.Errorf("invalid bucket name: %s", bucket)
}

var e *apierror.APIError
if errors.As(err, &e) && e.HTTPCode() == 409 {
    // name already exists: use it or pick a new unique name
}

When it happens

Trigger: CreateBucket called with a bucket name already used anywhere in GCS (409 conflict), a name violating bucket naming rules, a caller whose service account lacks storage.buckets.create, or invalid attrs (bad location/storage class).

Common situations: Retrying a create after a previous partial run (name now exists); picking common names like 'my-test-bucket' that are globally taken; creating in a project without the Cloud Storage API enabled; org policy forbidding certain locations.

Related errors

• failed to list objects in bucket %q: %w
• failed to open object %q in bucket %q: %w
• failed to list buckets in project %q: %w
• failed to get metadata for created bucket %q: %w
• object %q: %d bytes exceeds %d byte limit: %w

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