beemdevelopment/Aegis · error · VaultRepositoryException

Backup file already exists

Error message

Backup file already exists

What it means

createBackup refuses to start a backup when a file with the target name (FileInfo.toString(), normally the date-based name) already exists in the SAF directory. Because Storage Access Framework's createFile cannot overwrite and would silently create 'name (1).json' instead, the library throws VaultRepositoryException('Backup file already exists') to avoid duplicated or misleading backup files.

Solutions

  1. Delete the existing file first: dir.findFile(name).delete() (requires write grant on the tree), or pick a new filename that includes a timestamp with seconds
  2. Check existence before calling scheduleBackup and skip/log instead of throwing when the same-day backup is intentional
  3. Change the backup FileInfo to include a unique component (e.g. HHmmss or a UUID suffix) so collisions cannot recur
  4. Choose a different backup directory or move the stale file out

Example fix

// before
DocumentFile existing = dir.findFile(fileInfo.toString());
if (existing != null) { /* VaultRepositoryException: Backup file already exists */ }
// after
DocumentFile existing = dir.findFile(fileInfo.toString());
if (existing != null) {
    existing.delete(); // overwrite policy: replace stale backup
}
DocumentFile file = dir.createFile("application/json", fileInfo.toString());
Defensive patterns

Strategy: validation

Validate before calling

DocumentFile dir = DocumentFile.fromTreeUri(context, dirUri);
String name = fileInfo.toString();
if (dir.findFile(name) != null) {
    dir.findFile(name).delete(); // or generate a new unique name
}

Type guard

boolean fileExistsInDir(DocumentFile dir, String name) {
    return dir != null && name != null && dir.findFile(name) != null;
}

Try / catch

try {
    backupManager.scheduleBackup(dirUri, fileInfo);
} catch (VaultRepositoryException e) {
    if (e.getMessage() != null && e.getMessage().contains("already exists")) {
        backupManager.scheduleBackup(dirUri, fileInfo.withTimestampSeconds());
    }
}

Prevention

When it happens

Trigger: createBackup runs with a FileInfo whose filename matches an existing entry in dir (dir.findFile(...) != null); typically two backups scheduled with the same date bucket, a restored/copy-pasted backup file, or a user-picked folder that already contains Aegis exports.

Common situations: Running backup twice on the same day with a date-precision filename; a device clock misconfiguration reusing a previous backup name; user manually copies old backups into the chosen backup folder; restoring an app backup that includes the target directory.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of beemdevelopment/Aegis@d6f4e5925a (2026-09-08). Data as JSON: /api/errors/9e9ee9b4d915618c. Report an issue: GitHub.

Appendix: source

Thrown at app/src/main/java/com/beemdevelopment/aegis/vault/VaultBackupManager.java:126

    }

    private void createBackup(File tempFile, Uri dirUri, int versionsToKeep)
            throws VaultRepositoryException, VaultBackupPermissionException {
        FileInfo fileInfo = new FileInfo(FILENAME_PREFIX);
        DocumentFile dir = DocumentFile.fromTreeUri(_context, dirUri);

        try {
            Log.i(TAG, String.format("Creating backup at %s: %s", Uri.decode(dir.getUri().toString()), fileInfo.toString()));

            if (!hasPermissionsAt(dirUri)) {
                throw new VaultBackupPermissionException("No persisted URI permissions");
            }

            // If we create a file with a name that already exists, SAF will append a number
            // to the filename and write to that instead. We can't overwrite existing files, so
            // just avoid that altogether by checking beforehand.
            if (dir.findFile(fileInfo.toString()) != null) {
                throw new VaultRepositoryException("Backup file already exists");
            }

            DocumentFile file = dir.createFile("application/json", fileInfo.toString());
            if (file == null) {
                throw new VaultRepositoryException("createFile returned null");
            }

            try (FileInputStream inStream = new FileInputStream(tempFile);
                 OutputStream outStream = _context.getContentResolver().openOutputStream(file.getUri())) {
                if (outStream == null) {
                    throw new IOException("openOutputStream returned null");
                }
                IOUtils.copy(inStream, outStream);
            } catch (IOException e) {
                throw new VaultRepositoryException(e);
            }
        } catch (VaultRepositoryException | VaultBackupPermissionException e) {
            Log.e(TAG, String.format("Unable to create backup: %s", e.toString()));

View on GitHub (pinned to d6f4e5925a)