googleapis/mcp-toolbox · error

error restoring backup

Error message

error restoring backup: %w

What it means

This error wraps a failure from the Cloud SQL Admin API Instances.RestoreBackup call, which starts an asynchronous restore of a backup into a target instance. The restore operation was rejected or failed at submission time; the original Google API error is preserved for diagnosis.

Solutions

1. Inspect the wrapped Google API error for the specific cause (404 backup not found, 403 permission denied, 400 failedPrecondition)
2. Confirm targetProject/targetInstance exist and are in a state that accepts restores (not under maintenance)
3. Verify the source project/instance/backupRunId triple points to an existing backup (list BackupRuns to check)
4. Ensure the access token has Cloud SQL Admin permissions and retry; the restore is a long-running operation so poll the returned operation

// Verify the backup exists before restoring
srv, _ := sqladmin.NewService(ctx)
runs, err := srv.BackupRuns.List(sourceProject, sourceInstance).Do()
if err != nil || !containsBackupRun(runs, backupID) {
    return fmt.Errorf("backup run %d not found in %s/%s", backupID, sourceProject, sourceInstance)
}

resp, err := RestoreBackup(ctx, targetProject, targetInstance, srcProject, srcInstance, backupID, token)
if err != nil {
    var gerr *googleapi.Error
    if errors.As(err, &gerr) && (gerr.Code == 429 || gerr.Code >= 500) {
        // retry with backoff
    }
    return err
}

When it happens

Trigger: Calling RestoreBackup when the Instances.RestoreBackup RPC errors: target instance not found, backup ID does not exist in the source project/instance, insufficient IAM permissions, target instance state does not allow restore, or the point-in-time/backup context is invalid.

Common situations: Restoring into a misnamed target instance; referencing a backup run ID that was deleted or belongs to another project; service account lacking cloudsql.admin; target instance currently undergoing maintenance or with incompatibilities (e.g. different database flags/disk size).

Related errors

• error creating backup
• error creating instance
• could not marshal operation
• could not unmarshal operation
• error cloning instance

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

Appendix: source

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

		request.RestoreBackupContext = &sqladmin.RestoreBackupContext{
			Project:     sourceProject,
			InstanceId:  sourceInstance,
			BackupRunId: backupRunID,
		}
	} else if backupDRRegex.MatchString(backupID) {
		request.BackupdrBackup = backupID
	} else {
		request.Backup = backupID
	}

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

	resp, err := service.Instances.RestoreBackup(targetProject, targetInstance, request).Do()
	if err != nil {
		return nil, fmt.Errorf("error restoring backup: %w", err)
	}

	return resp, nil
}

func generateCloudSQLConnectionMessage(ctx context.Context, source *Source, logger log.Logger, opResponse map[string]any, connectionMessageTemplate string) (string, bool) {
	operationType, ok := opResponse["operationType"].(string)
	if !ok || operationType != "CREATE_DATABASE" {
		return "", false
	}

	targetLink, ok := opResponse["targetLink"].(string)
	if !ok {
		return "", false
	}

	matches := targetLinkRegex.FindStringSubmatch(targetLink)
	if len(matches) < 4 {

View on GitHub (pinned to 8cc6e09de2)