beemdevelopment/Aegis · error · VaultRepositoryException

createFile returned null

Error message

createFile returned null

What it means

After the existence check, createBackup calls DocumentFile.createFile('application/json', name); SAF providers can fail (unsupported MIME type, provider crash, storage full) and return null rather than throwing. The library converts that null into VaultRepositoryException('createFile returned null') so the failure is explicit.

Solutions

  1. Log the provider and URI, then retry the backup to a different location (e.g. local Downloads tree) to isolate the failing provider
  2. Try a MIME type the provider supports (e.g. 'application/octet-stream') or a simpler filename without provider-rejected characters
  3. Verify the target storage is writable (mount state, free space) before scheduling
  4. Catch this VaultRepositoryException in the caller and surface a backup-failed notification with actionable guidance

Example fix

// before
DocumentFile file = dir.createFile("application/json", fileInfo.toString());
// after
DocumentFile file = dir.createFile("application/json", fileInfo.toString());
if (file == null) {
    Log.e(TAG, "createFile failed for provider " + dirUri + "; falling back");
    dir = DocumentFile.fromTreeUri(context, fallbackTreeUri);
    file = dir.createFile("application/octet-stream", fileInfo.toString());
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (dir == null || !dir.canWrite()) {
    Log.e(TAG, "destination tree not writable: " + dirUri);
    return;
}

Type guard

boolean isUsableDestination(DocumentFile dir) {
    return dir != null && dir.exists() && dir.canWrite();
}

Try / catch

try {
    backupManager.scheduleBackup(dirUri, fileInfo);
} catch (VaultRepositoryException e) {
    if ("createFile returned null".equals(e.getMessage())) {
        showBackupDestinationProblemNotification();
    }
}

Prevention

When it happens

Trigger: The DocumentsProvider backing the tree URI fails to create the file and returns null: unsupported MIME type by the provider, invalid display name characters for the provider, storage volume unavailable/full, or remote provider error.

Common situations: Backing up to a cloud/external provider (e.g. SD card, NAS, third-party documents provider) that doesn't accept 'application/json'; provider bug on specific OEM ROMs; SD card ejected or read-only.

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 beemdevelopment/Aegis@d6f4e5925a (2026-09-08). Data as JSON: /api/errors/8936df91aa9fb453. Report an issue: GitHub.

Appendix: source

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

        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()));
            throw e;
        } finally {
            tempFile.delete();
        }

View on GitHub (pinned to d6f4e5925a)