{"record":{"id":"e7144ff78e64936c","repo":"googleapis/mcp-toolbox","slug":"error-creating-instance-w","errorCode":null,"errorMessage":"error creating instance: %w","messagePattern":"error creating instance: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/cloudsqladmin/cloud_sql_admin.go","lineNumber":337,"sourceCode":"}\n\nfunc (s *Source) CreateInstance(ctx context.Context, project, name, dbVersion, rootPassword string, settings sqladmin.Settings, accessToken string) (any, error) {\n\tinstance := sqladmin.DatabaseInstance{\n\t\tName:            name,\n\t\tDatabaseVersion: dbVersion,\n\t\tRootPassword:    rootPassword,\n\t\tSettings:        &settings,\n\t\tProject:         project,\n\t}\n\n\tservice, err := s.GetService(ctx, accessToken)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tresp, err := service.Instances.Insert(project, &instance).Do()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error creating instance: %w\", err)\n\t}\n\n\treturn resp, nil\n}\n\nfunc (s *Source) GetWaitForOperations(ctx context.Context, service *sqladmin.Service, project, operation, connectionMessageTemplate string, delay time.Duration) (any, error) {\n\tlogger, err := util.LoggerFromContext(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\top, err := service.Operations.Get(project, operation).Do()\n\tif err != nil {\n\t\tlogger.DebugContext(ctx, fmt.Sprintf(\"error getting operation: %s, retrying in %v\", err, delay))\n\t} else {\n\t\tif op.Status == \"DONE\" {\n\t\t\tif op.Error != nil {\n\t\t\t\tvar errorBytes []byte\n\t\t\t\terrorBytes, err = json.Marshal(op.Error)","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/cloudsqladmin/cloud_sql_admin.go#L319-L355","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the wrapped googleapi.Error details (message, code, errors[]) to identify the exact API rejection reason","Verify the access token has the cloudsql.admin (or cloudsql.instances.create) permission and is not expired","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)","Validate settings: tier (e.g. db-custom-...), region, and disk parameters match the chosen database version and are within quota","Retry after fixing quota/name conflicts; if transient (5xx), retry with backoff"],"exampleFix":"// before\nresp, err := service.Instances.Insert(project, &instance).Do()\nif err != nil {\n    return nil, fmt.Errorf(\"error creating instance: %w\", err)\n}\n// after\nresp, err := service.Instances.Insert(project, &instance).Do()\nif err != nil {\n    var gerr *googleapi.Error\n    if errors.As(err, &gerr) {\n        return nil, fmt.Errorf(\"error creating instance (code %d): %s\", gerr.Code, gerr.Message)\n    }\n    return nil, fmt.Errorf(\"error creating instance: %w\", err)\n}","handlingStrategy":"validation","validationCode":"// Pre-validate inputs before calling create instance\nfunc validateInstanceInput(project, name, dbVersion, rootPassword, tier, region string) error {\n    if project == \"\" || name == \"\" || dbVersion == \"\" || tier == \"\" || region == \"\" {\n        return fmt.Errorf(\"project, name, dbVersion, tier and region are required\")\n    }\n    if !regexp.MustCompile(`^[a-z][a-z0-9-]{0,97}$`).MatchString(name) {\n        return fmt.Errorf(\"instance name %q is invalid: lowercase letters, numbers, hyphens only\", name)\n    }\n    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}\n    if !supported[dbVersion] {\n        return fmt.Errorf(\"unsupported databaseVersion %q\", dbVersion)\n    }\n    if rootPassword == \"\" || len(rootPassword) < 8 {\n        return fmt.Errorf(\"rootPassword must be at least 8 characters for the chosen engine\")\n    }\n    return nil\n}","typeGuard":"// Unwrap and classify the googleapi error from the wrapped error\nfunc asGoogleAPIError(err error) (*googleapi.Error, bool) {\n    var gerr *googleapi.Error\n    if errors.As(err, &gerr) {\n        return gerr, true\n    }\n    return nil, false\n}","tryCatchPattern":"result, err := src.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, token)\nif err != nil {\n    if gerr, ok := asGoogleAPIError(err); ok {\n        switch gerr.Code {\n        case 409:\n            return fmt.Errorf(\"instance name already taken: retry with a different name\")\n        case 403:\n            return fmt.Errorf(\"permission denied: token needs cloudsql.admin (%v)\", gerr.Message)\n        case 429:\n            return fmt.Errorf(\"quota exceeded: request more quota or reduce usage\")\n        case >= 500:\n            return retryWithBackoff(func() error { _, err = src.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, token); return err })\n        }\n    }\n    return err\n}","preventionTips":["Uniquely name instances (suffix with project/timestamp) to avoid 409 name collisions","Ensure the access token comes from a service account with roles/cloudsql.admin and is refreshed before long operations","Validate dbVersion/tier/region combinations against Cloud SQL docs before submission","Monitor project Cloud SQL quota in the console and enable API (sqladmin.googleapis.com) beforehand"],"tags":["gcp","cloudsql","api-error","provisioning"],"backgroundTag":"cloud-api-request-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}