googleapis/mcp-toolbox · error

failed to list objects in bucket %q: %w

Error message

failed to list objects in bucket %q: %w

What it means

The GCS paginator (iterator.NewPager / NextPage) returned an error while listing objects in the bucket, and the source wraps it with this message. The underlying %w error carries the actual cause: an HTTP/gRPC failure from the Cloud Storage API, an auth problem, or a missing bucket.

Source

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

	if err := s.validateBucket(bucket); err != nil {
		return nil, err
	}
	it := s.client.Bucket(bucket).Objects(ctx, &storage.Query{
		Prefix:    prefix,
		Delimiter: delimiter,
	})
	// iterator.NewPager errors on pageSize <= 0; the tool layer already rejects
	// values above the GCS per-page cap of 1000, so any positive value is safe.
	ps := maxResults
	if ps <= 0 {
		ps = 1000
	}
	pager := iterator.NewPager(it, ps, pageToken)

	var attrsPage []*storage.ObjectAttrs
	nextPageToken, err := pager.NextPage(&attrsPage)
	if err != nil {
		return nil, fmt.Errorf("failed to list objects in bucket %q: %w", bucket, err)
	}

	objects := make([]*storage.ObjectAttrs, 0, len(attrsPage))
	prefixes := make([]string, 0)
	for _, attrs := range attrsPage {
		if attrs.Prefix != "" {
			prefixes = append(prefixes, attrs.Prefix)
			continue
		}
		objects = append(objects, attrs)
	}

	return map[string]any{
		"objects":       objects,
		"prefixes":      prefixes,
		"nextPageToken": nextPageToken,
	}, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Inspect the wrapped error: fix the bucket name or create the bucket if it is a 404.
2. Grant the service account storage.objects.list (e.g. roles/storage.objectViewer) on the bucket.
3. Verify credentials are configured (gcloud auth application-default login or GOOGLE_APPLICATION_CREDENTIALS) and not expired.
4. Fix network/proxy reachability to storage.googleapis.com, then retry with backoff on transient errors.

Example fix

// before
res, err := source.ListObjects(ctx, "my-proj-bucket", "", 100, "")
// after (validate access first)
if _, err := source.ListBuckets(ctx, "my-project", "", 1); err != nil {
    // fix credentials/IAM before retrying ListObjects
}
res, err := source.ListObjects(ctx, "my-proj-bucket", "", 100, "")

// verify auth + project access first
creds := os.Getenv("GOOGLE_APPLICATION_CREDENTIALS")
if creds == "" && os.Getenv("GOOGLE_CLOUD_PROJECT") == "" {
    return errors.New("no GCP credentials configured")
}

var e *apierror.APIError
if errors.As(err, &e) {
    switch e.HTTPCode() {
    case 404: // wrong bucket name
    case 403: // fix IAM
    default: // transient: retry with backoff
    }
}

When it happens

Trigger: Calling ListObjects with a pageToken/page size where pager.NextPage fails: bucket does not exist (404), caller lacks storage.objects.list IAM permission (403), unauthenticated/expired credentials, network unreachable, or an invalid continuation pageToken.

Common situations: Deleted or misspelled bucket name; service account without roles/storage.objectViewer on the bucket; Application Default Credentials not set (GOOGLE_APPLICATION_CREDENTIALS unset); running behind a proxy/firewall blocking storage.googleapis.com.

Related errors

• failed to open object %q in bucket %q: %w
• failed to read object %q in bucket %q: %w
• failed to list buckets in project %q: %w
• failed to create bucket %q in project %q: %w
• failed to list tables: %w

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