googleapis/mcp-toolbox · error

error restoring backup: %w

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.

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)

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 instance: %w
• error creating backup: %w
• error cloning instance: %w
• error creating database: %w
• error creating user: %w

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