googleapis/mcp-toolbox · error

error creating AlloyDB instance: %w

Error message

error creating AlloyDB instance: %w

What it means

This error wraps any failure returned by the AlloyDB Admin API's Instances.Create call, which submits a request to create a new instance inside an existing cluster. Because the underlying API returns a long-running operation, this error indicates the initial request itself failed (HTTP-level or request-construction error), not a later operation failure. The original Google API error is preserved via %w so callers can inspect it with errors.As/errors.Is.

Source

Thrown at internal/sources/alloydbadmin/alloydbadmin.go:201

	}

	if instanceType == "READ_POOL" {
		instance.ReadPoolConfig = &alloydbrestapi.ReadPoolConfig{
			NodeCount: int64(nodeCount),
		}
	}

	service, err := s.getService(ctx, accessToken)
	if err != nil {
		return nil, err
	}

	urlString := fmt.Sprintf("projects/%s/locations/%s/clusters/%s", project, location, cluster)

	// The Create API returns a long-running operation.
	resp, err := service.Projects.Locations.Clusters.Instances.Create(urlString, instance).InstanceId(instanceID).Do()
	if err != nil {
		return nil, fmt.Errorf("error creating AlloyDB instance: %w", err)
	}
	return resp, nil
}

func (s *Source) CreateUser(ctx context.Context, userType, password string, roles []string, accessToken, project, location, cluster, userID string) (any, error) {
	// Build the request body using the type-safe User struct.
	user := &alloydbrestapi.User{
		UserType: userType,
	}

	if userType == "ALLOYDB_BUILT_IN" {
		user.Password = password
	}

	if len(roles) > 0 {
		user.DatabaseRoles = roles
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify project, location, and cluster names are correct and the cluster exists via GetCluster before creating the instance
2. Check the instance ID is unique in the cluster and matches AlloyDB naming rules (lowercase letters, numbers, hyphens)
3. Ensure the access token has the https://www.googleapis.com/auth/cloud-platform or alloydb.admin scope and is not expired
4. Inspect the wrapped error with errors.As on *googleapi.Error to read the exact HTTP status and message
5. Retry with exponential backoff only on 429/5xx responses; 409/400 responses need input correction

Example fix

// before
resp, err := service.Projects.Locations.Clusters.Instances.Create(urlString, instance).InstanceId(instanceID).Do()
if err != nil { return nil, err }
// after
if _, err := s.GetCluster(ctx, project, location, cluster, accessToken); err != nil {
    return nil, fmt.Errorf("parent cluster check failed: %w", err)
}
resp, err := service.Projects.Locations.Clusters.Instances.Create(urlString, instance).InstanceId(instanceID).Do()
if err != nil {
    var gerr *googleapi.Error
    if errors.As(err, &gerr) && gerr.Code == 409 {
        return nil, fmt.Errorf("instance %s already exists in %s: %w", instanceID, cluster, err)
    }
    return nil, fmt.Errorf("error creating AlloyDB instance: %w", err)
}

// Go: validate inputs and parent cluster before CreateInstance
if cluster == "" || instanceID == "" {
    return fmt.Errorf("cluster and instanceID are required")
}
if _, err := s.GetCluster(ctx, project, location, cluster, accessToken); err != nil {
    return fmt.Errorf("parent cluster %s not reachable: %w", cluster, err)
}

func IsGoogleAPIError(err error) (*googleapi.Error, bool) {
    var gerr *googleapi.Error
    ok := errors.As(err, &gerr)
    return gerr, ok
}

resp, err := s.CreateInstance(ctx, project, location, cluster, instance, accessToken, ...)
if err != nil {
    var gerr *googleapi.Error
    if errors.As(err, &gerr) {
        switch gerr.Code {
        case 409:
            return fmt.Errorf("instance already exists")
        case 403, 401:
            return fmt.Errorf("auth failure, refresh token: %v", gerr)
        default:
            return retryable(gerr.Code, err)
        }
    }
    return err
}

When it happens

Trigger: Calling Source.CreateInstance when the parent cluster resource path is wrong, the instance ID is invalid or already exists, the OAuth access token lacks the alloydb.admin scope, or the REST call to projects/*/locations/*/clusters/*/instances returns a non-2xx response.

Common situations: Typos in project/location/cluster names, creating an instance whose ID already exists in the cluster, expired or scope-limited access tokens, network egress blocked to the alloydb.googleapis.com endpoint, or instance fields violating API validation (e.g., invalid machine type).

Related errors

• error creating AlloyDB user: %w
• error getting AlloyDB cluster: %w
• error getting AlloyDB instance: %w
• error getting AlloyDB user: %w
• error listing AlloyDB clusters: %w

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