googleapis/mcp-toolbox · error

failed to create instance: %w

Error message

failed to create instance: %w

What it means

This error wraps a failure from InstanceAdmin.CreateInstance when provisioning a new Bigtable instance with the given display name, cluster, zone, and node count. Common causes are invalid configuration (bad zone, duplicate cluster/instance ID, insufficient nodes), quota limits, or IAM/permission failures. The original API error is preserved via %w.

Source

Thrown at internal/sources/bigtable/admin_wrappers.go:44

func (s *Source) GetInstance(ctx context.Context, instanceId string) (any, error) {
	instance, err := s.InstanceAdmin.InstanceInfo(ctx, instanceId)
	if err != nil {
		return nil, fmt.Errorf("failed to get instance: %w", err)
	}
	return instance, nil
}

func (s *Source) CreateInstance(ctx context.Context, instanceId, displayName, clusterId, zone string, numNodes int32) (any, error) {
	conf := &bigtable.InstanceConf{
		InstanceId:  instanceId,
		DisplayName: displayName,
		ClusterId:   clusterId,
		Zone:        zone,
		NumNodes:    numNodes,
	}
	err := s.InstanceAdmin.CreateInstance(ctx, conf)
	if err != nil {
		return nil, fmt.Errorf("failed to create instance: %w", err)
	}
	return map[string]string{"status": "instance created successfully"}, nil
}

func (s *Source) UpdateInstance(ctx context.Context, instanceId, displayName string) (any, error) {
	conf := &bigtable.InstanceWithClustersConfig{
		InstanceID:  instanceId,
		DisplayName: displayName,
	}
	err := s.InstanceAdmin.UpdateInstanceWithClusters(ctx, conf)
	if err != nil {
		return nil, fmt.Errorf("failed to update instance: %w", err)
	}
	return map[string]string{"status": "instance updated successfully"}, nil
}

func (s *Source) DeleteInstance(ctx context.Context, instanceId string) (any, error) {
	err := s.InstanceAdmin.DeleteInstance(ctx, instanceId)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Validate the zone is a real Bigtable zone (e.g. us-east1-b): check `gcloud bigtable clusters create --zone` docs or `gcloud compute zones list`.
2. Ensure the instanceId is unique in the project; check `gcloud bigtable instances list`.
3. Confirm numNodes meets Bigtable minimums (>=3 for production clusters) and project quota allows it.
4. Grant the caller roles/bigtable.admin on the project.
5. Read the wrapped status error — AlreadyExists, InvalidArgument, or ResourceExhausted point to the exact problem.

Example fix

// before
conf := &bigtable.InstanceConf{ InstanceID: instanceId, DisplayName: displayName, ClusterId: clusterId, Zone: zone, NumNodes: numNodes }
err := s.InstanceAdmin.CreateInstance(ctx, conf)
if err != nil {
    return nil, fmt.Errorf("failed to create instance: %w", err)
}
// after
if numNodes < 3 {
    return nil, fmt.Errorf("numNodes must be >= 3 for production cluster, got %d", numNodes)
}
err := s.InstanceAdmin.CreateInstance(ctx, conf)
if err != nil {
    if st, ok := status.FromError(err); ok && st.Code() == codes.AlreadyExists {
        return nil, fmt.Errorf("instance %q already exists: %w", instanceId, err)
    }
    return nil, fmt.Errorf("failed to create instance %q (zone=%s, nodes=%d): %w", instanceId, zone, numNodes, err)
}

zones := map[string]bool{"us-east1-b": true, "us-central1-a": true /* populate from gcloud compute zones list */}
if instanceId == "" || clusterId == "" || !zones[zone] {
    return fmt.Errorf("invalid create-instance params: id=%q cluster=%q zone=%q", instanceId, clusterId, zone)
}
if numNodes < 3 {
    return fmt.Errorf("numNodes must be >= 3, got %d", numNodes)
}

func validInstanceConf(conf *bigtable.InstanceConf) error {
    if conf == nil || conf.InstanceID == "" || conf.ClusterId == "" || conf.Zone == "" {
        return errors.New("instanceId, clusterId and zone are required")
    }
    if conf.NumNodes < 3 {
        return fmt.Errorf("numNodes must be >= 3, got %d", conf.NumNodes)
    }
    return nil
}

_, err := src.CreateInstance(ctx, id, name, cluster, zone, nodes)
if err != nil {
    if st, ok := status.FromError(err); ok {
        switch st.Code() {
        case codes.AlreadyExists:
            return fmt.Errorf("instance %q already exists", id)
        case codes.ResourceExhausted:
            return fmt.Errorf("quota exceeded; request quota increase")
        case codes.PermissionDenied:
            return fmt.Errorf("requires roles/bigtable.admin: %w", err)
        }
    }
    return err
}

When it happens

Trigger: Calling CreateInstance(ctx, instanceId, displayName, clusterId, zone, numNodes) with an instance ID that already exists, an unsupported/misspelled zone, numNodes below the minimum, exceeding project quota, or lacking roles/bigtable.admin.

Common situations: Tool caller inventing a zone name like 'us-central1' instead of 'us-central1-a', duplicate create invoked twice, project hitting the instance/node quota, service account without Bigtable Admin role.

Related errors

• operation finished with error: %s
• failed to get instance: %w
• failed to update instance: %w
• failed to delete instance: %w
• failed to list instances: %w

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