googleapis/mcp-toolbox · error

error listing instances: %w

Error message

error listing instances: %w

What it means

Thrown in ListInstance when the sqladmin Instances.List call (projects.instances.list) fails. Listing all Cloud SQL instances in a project returned an API error before the empty-items normalization.

Source

Thrown at internal/sources/cloudsqladmin/cloud_sql_admin.go:281

	for _, item := range resp.Items {
		databases = append(databases, databaseInfo{
			Name:      item.Name,
			Charset:   item.Charset,
			Collation: item.Collation,
		})
	}
	return databases, nil
}

func (s *Source) ListInstance(ctx context.Context, project, accessToken string) (any, error) {
	service, err := s.GetService(ctx, accessToken)
	if err != nil {
		return nil, err
	}

	resp, err := service.Instances.List(project).Do()
	if err != nil {
		return nil, fmt.Errorf("error listing instances: %w", err)
	}

	if resp.Items == nil {
		return []any{}, nil
	}

	type instanceInfo struct {
		Name         string `json:"name"`
		InstanceType string `json:"instanceType"`
	}

	var instances []instanceInfo
	for _, item := range resp.Items {
		instances = append(instances, instanceInfo{
			Name:         item.Name,
			InstanceType: item.InstanceType,
		})
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the project ID is correct and the Cloud SQL Admin API is enabled.
2. Grant roles/cloudsql.viewer to the calling principal.
3. Retry with backoff on 429/5xx responses.
4. Inspect the wrapped googleapi.Error code and message.
5. Confirm no VPC Service Controls perimeter is blocking sqladmin.googleapis.com.

Example fix

null

if project == "" {
    return fmt.Errorf("project is required to list instances")
}
// confirm project is valid
if _, err := resourcemanagerService.Projects.Get(project).Do(); err != nil {
    return fmt.Errorf("invalid or inaccessible project %q: %w", project, err)
}

func isRateLimited(err error) bool {
    var gerr *googleapi.Error
    return errors.As(err, &gerr) && gerr.Code == 429
}

var out any
var err error
backoff := time.Second
for attempt := 0; attempt < 4; attempt++ {
    out, err = src.ListInstance(ctx, project, token)
    if err == nil || !isRateLimited(err) {
        break
    }
    time.Sleep(backoff)
    backoff *= 2
}
if err != nil {
    return fmt.Errorf("list instances failed: %w", err)
}

When it happens

Trigger: Calling the list_instances tool with an invalid project ID, a principal lacking cloudsql.instances.list permission, or during a transient Cloud SQL API outage.

Common situations: Misconfigured project ID in the tool arguments; service account without roles/cloudsql.viewer; org policy or API not enabled; rate limiting (429) on very active projects.

Related errors

• error listing databases: %w
• error cloning instance: %w
• error creating database: %w
• error creating user: %w
• error getting instance: %w

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