googleapis/mcp-toolbox · error

error creating instance: %w

Error message

error creating instance: %w

What it means

This error wraps any failure returned by the Cloud SQL Admin API's Instances.Insert call when trying to create a new Cloud SQL instance. The library builds a sqladmin.DatabaseInstance from the tool parameters (name, dbVersion, rootPassword, settings) and submits it to the API; if Google's API rejects the request (invalid params, quota, permissions, name collision, etc.), the underlying googleapi.Error is wrapped with this message. The root cause is always in the wrapped %w error.

Source

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

}

func (s *Source) CreateInstance(ctx context.Context, project, name, dbVersion, rootPassword string, settings sqladmin.Settings, accessToken string) (any, error) {
	instance := sqladmin.DatabaseInstance{
		Name:            name,
		DatabaseVersion: dbVersion,
		RootPassword:    rootPassword,
		Settings:        &settings,
		Project:         project,
	}

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

	resp, err := service.Instances.Insert(project, &instance).Do()
	if err != nil {
		return nil, fmt.Errorf("error creating instance: %w", err)
	}

	return resp, nil
}

func (s *Source) GetWaitForOperations(ctx context.Context, service *sqladmin.Service, project, operation, connectionMessageTemplate string, delay time.Duration) (any, error) {
	logger, err := util.LoggerFromContext(ctx)
	if err != nil {
		return nil, err
	}
	op, err := service.Operations.Get(project, operation).Do()
	if err != nil {
		logger.DebugContext(ctx, fmt.Sprintf("error getting operation: %s, retrying in %v", err, delay))
	} else {
		if op.Status == "DONE" {
			if op.Error != nil {
				var errorBytes []byte
				errorBytes, err = json.Marshal(op.Error)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped googleapi.Error details (message, code, errors[]) to identify the exact API rejection reason
2. Verify the access token has the cloudsql.admin (or cloudsql.instances.create) permission and is not expired
3. Check the instance name is valid (lowercase, hyphens/numbers, unique within project) and databaseVersion is a supported API value (e.g. POSTGRES_15, MYSQL_8_0)
4. Validate settings: tier (e.g. db-custom-...), region, and disk parameters match the chosen database version and are within quota
5. Retry after fixing quota/name conflicts; if transient (5xx), retry with backoff

Example fix

// before
resp, err := service.Instances.Insert(project, &instance).Do()
if err != nil {
    return nil, fmt.Errorf("error creating instance: %w", err)
}
// after
resp, err := service.Instances.Insert(project, &instance).Do()
if err != nil {
    var gerr *googleapi.Error
    if errors.As(err, &gerr) {
        return nil, fmt.Errorf("error creating instance (code %d): %s", gerr.Code, gerr.Message)
    }
    return nil, fmt.Errorf("error creating instance: %w", err)
}

// Pre-validate inputs before calling create instance
func validateInstanceInput(project, name, dbVersion, rootPassword, tier, region string) error {
    if project == "" || name == "" || dbVersion == "" || tier == "" || region == "" {
        return fmt.Errorf("project, name, dbVersion, tier and region are required")
    }
    if !regexp.MustCompile(`^[a-z][a-z0-9-]{0,97}$`).MatchString(name) {
        return fmt.Errorf("instance name %q is invalid: lowercase letters, numbers, hyphens only", name)
    }
    supported := map[string]bool{"MYSQL_5_7": true, "MYSQL_8_0": true, "POSTGRES_14": true, "POSTGRES_15": true, "POSTGRES_16": true, "SQLSERVER_2022_STANDARD": true}
    if !supported[dbVersion] {
        return fmt.Errorf("unsupported databaseVersion %q", dbVersion)
    }
    if rootPassword == "" || len(rootPassword) < 8 {
        return fmt.Errorf("rootPassword must be at least 8 characters for the chosen engine")
    }
    return nil
}

// Unwrap and classify the googleapi error from the wrapped error
func asGoogleAPIError(err error) (*googleapi.Error, bool) {
    var gerr *googleapi.Error
    if errors.As(err, &gerr) {
        return gerr, true
    }
    return nil, false
}

result, err := src.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, token)
if err != nil {
    if gerr, ok := asGoogleAPIError(err); ok {
        switch gerr.Code {
        case 409:
            return fmt.Errorf("instance name already taken: retry with a different name")
        case 403:
            return fmt.Errorf("permission denied: token needs cloudsql.admin (%v)", gerr.Message)
        case 429:
            return fmt.Errorf("quota exceeded: request more quota or reduce usage")
        case >= 500:
            return retryWithBackoff(func() error { _, err = src.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, token); return err })
        }
    }
    return err
}

When it happens

Trigger: Calling the create-instance tool where service.Instances.Insert(project, &instance).Do() returns an error: invalid instance name, unsupported databaseVersion, missing/invalid rootPassword for the chosen version, insufficient IAM permissions (cloudsql.admin), quota exceeded, duplicate instance name in project, or invalid settings (tier, region, disk size).

Common situations: Developers hit this when provisioning Cloud SQL via MCP toolbox: instance name violating naming rules (lowercase letters, numbers, hyphens, <=98 chars), wrong region/tier combos, expired or under-scoped access token, quota exhausted in the project, or an instance with the same name already existing.

Related errors

• operation finished with error: %s
• error creating backup: %w
• error restoring backup: %w
• failed to create instance: %w
• error cloning instance: %w

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