MuntashirAkon/AppManager · error · BackupException

Could not create BackupItem.

Error message

Could not create BackupItem.

What it means

BackupManager.backup resolves/creates the on-disk BackupItem for the target package (findOrCreateBackupItem or createBackupItemGracefully). Any IOException from that step (unreadable/unwritable backup location, existing backup conflicts, etc.) is rethrown as BackupException with this message and the original cause attached.

Source

Thrown at app/src/main/java/io/github/muntashirakon/AppManager/backup/BackupManager.java:78

    }

    public void backup(@NonNull BackupOpOptions options, @Nullable ProgressHandler progressHandler)
            throws BackupException {
        if (options.packageName.equals("android")) {
            throw new BackupException("Android System (android) cannot be backed up.");
        }
        if (options.flags.isEmpty()) {
            throw new BackupException("Backup is requested without any flags.");
        }
        BackupItems.BackupItem backupItem;
        try {
            if (options.override) {
                backupItem = BackupItems.findOrCreateBackupItem(options.userId, options.backupName, options.packageName);
            } else {
                backupItem = BackupItems.createBackupItemGracefully(options.userId, options.backupName, options.packageName);
            }
        } catch (IOException e) {
            throw new BackupException("Could not create BackupItem.", e);
        }
        if (progressHandler != null) {
            int max = calculateMaxProgress(options.flags);
            progressHandler.setProgressTextInterface(ProgressHandler.PROGRESS_PERCENT);
            progressHandler.postUpdate(max, 0f);
        }
        try (BackupOp backupOp = new BackupOp(options.packageName, options.flags, backupItem, options.userId)) {
            backupOp.runBackup(progressHandler);
            BackupUtils.putBackupToDbAndBroadcast(ContextUtils.getContext(), backupOp.getMetadata());
        }
    }

    /**
     * Restore a single backup for a given package belonging to the given package
     */
    public void restore(@NonNull RestoreOpOptions options, @Nullable ProgressHandler progressHandler)
            throws BackupException {
        if (options.packageName.equals("android")) {

View on GitHub (pinned to 0152f468fc)

Solutions

  1. Read getCause() of the BackupException to find the underlying IOException and fix that root cause
  2. Verify the backup directory is writable and has free space
  3. Use override=true (or delete the existing backup) if a stale backup blocks creation
  4. Choose a valid backup name (no illegal path characters)

Example fix

// before
try {
    backupManager.backup(options, null);
} catch (BackupException e) {
    Log.e(TAG, "backup failed", e);
}
// after
try {
    backupManager.backup(options, null);
} catch (BackupException e) {
    if (e.getCause() instanceof IOException) {
        // e.g. re-grant SAF permissions or free space, then retry
        Log.e(TAG, "backup storage problem: " + e.getCause().getMessage());
    }
}
Defensive patterns

Strategy: try-catch

Validate before calling

// verify backup storage is usable before calling backup
if (!backupRoot.exists() && !backupRoot.mkdirs()) { /* fix storage first */ }
if (backupRoot.getFreeSpace() < minRequired) { /* free space */ }

Try / catch

try {
    backupManager.backup(options, progressHandler);
} catch (BackupException e) {
    Throwable cause = e.getCause(); // IOException from BackupItem creation
    Log.e(TAG, "BackupItem creation failed", cause);
    // fix storage/permissions/name, then retry
}

Prevention

When it happens

Trigger: Calling BackupManager.backup where BackupItems.createBackupItemGracefully (no override) or findOrCreateBackupItem (override=true) throws IOException — e.g. the backup directory cannot be created or an existing backup cannot be opened.

Common situations: Unwritable or full storage, SAF permission revoked for the backup folder, corrupted existing backup metadata when overriding, invalid backup name characters.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of MuntashirAkon/AppManager@0152f468fc (2026-09-12). Data as JSON: /api/errors/df8503c308222d3e. Report an issue: GitHub.