{"record":{"id":"325ef811caf46029","repo":"googleapis/mcp-toolbox","slug":"pre-check-operation-failed-with-error-s","errorCode":null,"errorMessage":"pre-check operation failed with error: %s","messagePattern":"pre-check operation failed with error: (.+?)","errorType":"http","errorClass":"ClientServerError","httpStatus":500,"severity":"error","filePath":"internal/tools/cloudsqlpg/cloudsqlpgupgradeprecheck/cloudsqlpgupgradeprecheck.go","lineNumber":195,"sourceCode":"\t\treturn nil, util.ProcessGcpError(err)\n\t}\n\n\tconst pollTimeout = 20 * time.Second\n\tcutoffTime := time.Now().Add(pollTimeout)\n\n\tfor time.Now().Before(cutoffTime) {\n\t\tcurrentOp, err := service.Operations.Get(project, op.Name).Context(ctx).Do()\n\t\tif err != nil {\n\t\t\treturn nil, util.ProcessGcpError(err)\n\t\t}\n\n\t\tif currentOp.Status == \"DONE\" {\n\t\t\tif currentOp.Error != nil && len(currentOp.Error.Errors) > 0 {\n\t\t\t\terrMsg := fmt.Sprintf(\"pre-check operation LRO failed: %s\", currentOp.Error.Errors[0].Message)\n\t\t\t\tif currentOp.Error.Errors[0].Code != \"\" {\n\t\t\t\t\terrMsg = fmt.Sprintf(\"%s (Code: %s)\", errMsg, currentOp.Error.Errors[0].Code)\n\t\t\t\t}\n\t\t\t\treturn nil, util.NewClientServerError(errMsg, http.StatusInternalServerError, fmt.Errorf(\"pre-check operation failed with error: %s\", errMsg))\n\t\t\t}\n\n\t\t\tvar preCheckItems []*sqladmin.PreCheckResponse\n\t\t\tif currentOp.PreCheckMajorVersionUpgradeContext != nil {\n\t\t\t\tpreCheckItems = currentOp.PreCheckMajorVersionUpgradeContext.PreCheckResponse\n\t\t\t}\n\t\t\t// convertResults handles nil or empty preCheckItems\n\t\t\treturn PreCheckAPIResponse{Items: convertResults(preCheckItems)}, nil\n\t\t}\n\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn nil, util.NewClientServerError(\"timed out waiting for operation\", http.StatusRequestTimeout, ctx.Err())\n\t\tcase <-time.After(5 * time.Second):\n\t\t}\n\t}\n\treturn op, nil\n}","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/tools/cloudsqlpg/cloudsqlpgupgradeprecheck/cloudsqlpgupgradeprecheck.go#L177-L213","documentation":"The Cloud SQL Admin pre-check long-running operation (LRO) completed with status DONE but carried a non-empty error list, meaning Google's pre-check for the major version upgrade rejected the operation. The tool surfaces the first error's message (and code, if present) as a 500-class client server error.","triggerScenarios":"Invoking cloudsqlpg-upgrade-precheck where the LRO returned DONE with currentOp.Error.Errors non-empty — e.g. unsupported version path, insufficient disk/ML capacity checks failing, instance state not eligible for upgrade, or IAM permission problems on the Cloud SQL Admin API.","commonSituations":"Pre-checking an upgrade from an unsupported minor version; instance with read replicas or HA settings blocking the path; quota/permission denials surfacing as LRO errors; regional capacity unavailable for the target version.","solutions":["Read the embedded errMsg (message plus Code) — it comes from the Cloud SQL API and names the blocking condition","Fix the flagged condition (e.g. upgrade through intermediate versions, adjust instance settings, grant sqladmin roles)","Re-run the pre-check after correcting; if transient (capacity/quota), retry later","Check the operation ID in Cloud Audit Logs / Cloud Console for the full error detail"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-validate instance eligibility via Cloud SQL Admin API before invoking:\nop, err := sqladminService.Instances.Get(project, instance).Do()\nif err != nil || op.Settings.DataDiskSizeGb < required { return fmt.Errorf(\"instance not eligible for pre-check\") }","typeGuard":"func opFailed(op *sqladmin.Operation) (string, bool) {\n    if op.Status == \"DONE\" && op.Error != nil && len(op.Error.Errors) > 0 {\n        return op.Error.Errors[0].Message, true\n    }\n    return \"\", false\n}","tryCatchPattern":"result, err := tool.Invoke(ctx, src, params, token)\nif err != nil {\n    // errMsg contains the Cloud SQL error message and code, e.g. \"(Code: ...)\n    if isRetryableCode(err) { backoffAndRetry(ctx, tool, args) }\n    return fmt.Errorf(\"upgrade pre-check rejected: %w\", err)\n}","preventionTips":["Check supported upgrade paths in Cloud SQL docs before invoking pre-check","Ensure the caller's service account has roles/cloudsql.admin","Inspect the failing operation in Cloud Console > Cloud SQL > Operations for the full error","Handle the embedded error code explicitly (quota/capacity errors are retryable; config errors are not)"],"tags":["cloudsql","gcp-api","lro","upgrade-precheck"],"backgroundTag":"cloudsql-lro-operation-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"}