Skip to content

Most visited

Recently visited

navigation

Testing Backup and Restore

This page shows you how to manually trigger Auto Backup, Key/Value Backup, and restore operations to ensure your app saves and restores data properly.

How backup works

The section describes various pieces in the Android backup framework and how they interact with apps that support Auto Backup and Key/Value Backup. During the app development phase, most of the inner working of the framework were abstracted away, so you didn't need to know this information. However, during the testing phase, an understanding of these concepts is important.

The following diagram illustrates how data flows during backup and restore: backup-framework

The Backup Manager Service is an Android system service which orchestrates and initiates backup and restore operations. The service is accessible through the BackupManager API. During a backup operation, the service queries your app for backup data, then hands it to the backup transport, which then archives the data. During a restore operation, the backup manager service retrieves the backup data from the backup transport and restores the data to the device.

Backup Transports are Android components that are responsible for storing and retrieving backups. An Android device can have zero or more backup transports, but only one of those transports can be marked active. The available backup transports may differ from device to device (due to customizations by device manufacturers and service providers), but most Google Play enabled devices ship with the following transports:

If a device does not have any backup transports, then the data cannot be backed up. Your app is not adversely affected.

Caution: Because the backup transport can differ from device to device, Android cannot guarantee the security of your data while using backup. Be cautious about using backup to store sensitive data, such as usernames and passwords.

Prerequisites

You need to know a bit about the following tools:

Preparing your device or emulator

Prepare your device or emulator for backup testing by working through the following checklist:

Physical devices without Google Play and emulators without Google APIs might not include the Google Backup Transport. This article assumes you are using the Google Backup Transport. You can test backup and restore with other backup transports, but the procedure and output can differ.

Testing backup

To initiate a backup of your app, run the following command:

$ adb shell bmgr backupnow <PACKAGE>

The backupnow command is available on devices and emulator running Android 7.0 or later. It runs either a Key/Value Backup or Auto Backup depending on the package's manifest declarations. Check logcat to see the output of the backup procedure. For example:

D/BackupManagerService: fullTransportBackup()
I/GmsBackupTransport: Attempt to do full backup on <PACKAGE>

---- or ----

V/BackupManagerService: Scheduling immediate backup pass
D/PerformBackupTask: starting key/value Backup of BackupRequest{pkg=<PACKAGE>}

If the backupnow command is not available on your device, complete the steps below for either Auto Backups or Key/Value Backups.

For Auto Backups, complete the following steps:

  1. Run the following command:
    $ adb shell bmgr backup @pm@ && adb shell bmgr run
    
  2. Wait until the command in the previous step finishes by monitoring adb logcat for the following output:
    I/BackupManagerService: K/V backup pass finished.
    
  3. Run the following command to perform a full backup:
    $ adb shell bmgr fullbackup <PACKAGE>
    

Note: The fullbackup command forces your app to perform a full backup, even if your app implements key/value backup. The system ignores your app's backup configuration and acts as if the android:fullBackupOnly attribute were set to true.

For Key/Value Backups, schedule and run your backup with the following steps:

  1. If your app hasn't called BackupManager.dataChanged() since the last backup, you can include your app in the backup operation for testing purposes by running the following command:
    $ adb shell bmgr backup <PACKAGE>
    
  2. You can then trigger a backup by running the following command:
    $ adb shell bmgr run
    

bmgr backup adds your app to the Backup Manager's queue. bmgr run initiates the backup operation, which forces the Backup Manager to perform all backup requests that are in its queue.

When testing Key/Value Backups, you must verify that every preference change schedules a backup. You can verify that a backup is scheduled using one of the following methods:

Testing restore

To manually initiate a restore, run the following command:

$ adb shell bmgr restore <TOKEN> <PACKAGE>

Warning: This action stops your app and wipes its data before performing the restore operation.

To look up backup tokens, run adb shell dumpsys backup. The token is the hexidecimal string following the labels Ancestral: and Current:. The ancestral token refers to the backup dataset that was used to restore the device when it was initially setup (with the device-setup wizard). The current token refers to the device's current backup dataset (the dataset that the device is currently sending its backup data to).

Then, check logcat to see the output of the restore procedure. For example:

V/BackupManagerService: beginRestoreSession: pkg=<PACKAGE> transport=null
V/RestoreSession: restorePackage pkg=<PACKAGE> token=368abb4465c5c683
...
I/BackupManagerService: Restore complete.

You also can test automatic restore for your app by uninstalling and reinstalling your app either with adb or through the Google Play Store app.

Troubleshooting

This section helps you troubleshoot some common issues.

Transport quota exceeded

If you see the following messages in logcat:

I/PFTBT: Transport rejected backup of <PACKAGE>, skipping

--- or ---

I/PFTBT: Transport quota exceeded for package: <PACKAGE>

Your app has exceeded the quota. Reduce the amount of backup data and try again. For example, verify that you are caching data only in the cache directory of your app. The cache directory isn't included in backups.

Full backup not possible

If you see the following message in logcat:

I/BackupManagerService: Full backup not currently possible -- key/value backup not yet run?

The fullbackup operation failed because no Key/Value Backup operation has yet occurred on the device. Trigger a Key/Value Backup with the command bmgr run and then try again.

Timeout waiting for agent

If you see the following message in logcat:

12-05 18:59:02.033  1910  2251 D BackupManagerService:
    awaiting agent for ApplicationInfo{5c7cde0 com.your.app.package}
12-05 18:59:12.117  1910  2251 W BackupManagerService:
    Timeout waiting for agent ApplicationInfo{5c7cde0 com.your.app.package}
12-05 18:59:12.117  1910  2251 W BackupManagerService:
    Can't find backup agent for com.your.app.package

Your app is taking more than 10 seconds to launch for backup. Notice the timestamp difference in the log output. This error typically occurs when your app makes use of a multidex configuration without ProGuard, and may be caused by Instant Run in Android Studio. To workaround the error, use ProGuard and don't use Instant Run.

Uninitialized backup account

If you see the following messages in logcat:

01-31 14:32:45.698 17280 17292 I Backup: [GmsBackupTransport] Try to backup for an uninitialized backup account.
01-31 14:32:45.699  1043 18255 W PFTBT: Transport failed; aborting backup: -1001
01-31 14:32:45.699  1043 18255 I PFTBT: Full backup completed with status: -1000

The backup was aborted because the backup dataset was not initialized. Run the backup manager with the command adb shell bmgr run and then try to perform the backup again.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)