googleapis/mcp-toolbox · error

failed to list buckets in project %q: %w

Error message

failed to list buckets in project %q: %w

What it means

The bucket paginator (iterator.NewPager / NextPage) failed while listing buckets in the GCP project; the source wraps the client error. The underlying error distinguishes auth/IAM failures (403), invalid project (404), and network problems.

Source

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

// there are no more results).
func (s *Source) ListBuckets(ctx context.Context, project, prefix string, maxResults int, pageToken string) (map[string]any, error) {
	if project == "" {
		project = s.Project
	}
	it := s.client.Buckets(ctx, project)
	if prefix != "" {
		it.Prefix = prefix
	}
	ps := maxResults
	if ps <= 0 {
		ps = 1000
	}
	pager := iterator.NewPager(it, ps, pageToken)

	var buckets []*storage.BucketAttrs
	nextPageToken, err := pager.NextPage(&buckets)
	if err != nil {
		return nil, fmt.Errorf("failed to list buckets in project %q: %w", project, err)
	}
	return map[string]any{
		"buckets":       buckets,
		"nextPageToken": nextPageToken,
	}, nil
}

// 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}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the project ID string (not number, no domain suffix) exists via `gcloud projects list`.
2. Grant the caller's service account storage.buckets.list on the project (e.g. roles/storage.objectAdmin or Viewer at project level).
3. Ensure Application Default Credentials are set and valid for the target project (GOOGLE_APPLICATION_CREDENTIALS / gcloud auth application-default login).
4. Retry with backoff on transient network/5xx errors; regenerate an invalid pageToken by restarting the listing.

Example fix

// before
res, err := source.ListBuckets(ctx, "123456789", "", 100, "") // project number, not ID
// after
res, err := source.ListBuckets(ctx, "my-actual-project-id", "", 100, "")

// verify project id format: lowercase letters, digits, hyphens
var projectRe = regexp.MustCompile(`^[a-z][a-z0-9-]{4,28}[a-z0-9]$`)
if !projectRe.MatchString(project) {
    return fmt.Errorf("invalid GCP project id: %s", project)
}

var e *apierror.APIError
if errors.As(err, &e) {
    switch e.HTTPCode() {
    case 403: // missing storage.buckets.list IAM
    case 404: // wrong project id
    default: // transient: retry
    }
}

When it happens

Trigger: ListBuckets called with a project ID that doesn't exist or is misspelled, a caller lacking storage.buckets.list (resourcemanager projects need roles/storage.admin or at least browser access on the project), invalid pageToken, expired credentials, or network failure.

Common situations: Passing a project number or folder/org ID instead of the project ID; service account without project-level storage permissions; wrong project configured in credentials vs. the one queried; ADC not set up in the runtime environment.

Related errors

• failed to list objects in bucket %q: %w
• failed to open object %q in bucket %q: %w
• failed to create bucket %q in project %q: %w
• object %q: %d bytes exceeds %d byte limit: %w
• failed to read object %q in bucket %q: %w

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