beemdevelopment/Aegis · error · VaultFileException

unsupported version

Error message

unsupported version

What it means

VaultFile.fromJson parses the on-disk vault JSON and enforces that the stored 'version' field is not newer than the VERSION constant this build of Aegis supports. If obj.getInt("version") > VERSION it throws VaultFileException('unsupported version'), refusing to open a vault written by a newer app release to prevent silently mis-parsing future formats.

Solutions

1. Update Aegis to the latest version (a build whose VERSION >= the file's version) and retry unlocking
2. Open the vault file with the newer Aegis install it came from, re-export/downgrade the vault, then import here
3. Verify you are loading the intended vault file (an old backup vs the migrated one)
4. If unavoidable, file an issue to obtain a build that supports the format; never hand-edit the version field

Example fix

// before
JSONObject obj = new JSONObject(vaultJson); // {"version": 3, ...} on app supporting 2
VaultFile file = VaultFile.fromJson(obj); // VaultFileException: unsupported version
// after
JSONObject obj = new JSONObject(vaultJson);
if (obj.optInt("version", VaultFile.VERSION) > VaultFile.VERSION) {
    promptUserToUpdateApp(); // offer newer release that supports the format
} else {
    VaultFile file = VaultFile.fromJson(obj);
}

JSONObject obj = new JSONObject(vaultJson);
if (obj.optInt("version", Integer.MAX_VALUE) > VaultFile.VERSION) {
    offerAppUpdate();
    return;
}

boolean isReadableVaultVersion(JSONObject obj) {
    return obj != null && obj.optInt("version", Integer.MAX_VALUE) <= VaultFile.VERSION;
}

try {
    VaultFile vf = VaultFile.fromJson(obj);
} catch (VaultFileException e) {
    if (e.getMessage().contains("unsupported version")) {
        promptAppUpdateOrNewerAegis();
    }
}

When it happens

Trigger: Opening a vault file exported by a newer Aegis version (higher VERSION constant) in an older app build; restoring an old backup of the app alongside a newer vault file; downgrading the app after vault migration.

Common situations: User downgrades the APK or installs an older F-Droid build while their vault was written by a newer release; sync service restores a newer vault onto a device with an older app; enterprise managed rollout lag.

Related errors

• unrecognized slot type
• Unable to decode stream to bitmap
• Unable to find pack.json in the root of the ZIP file
• Unable to create directories
• Unable to find relative to the root of the ZIP file

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

Appendix: source

Thrown at app/src/main/java/com/beemdevelopment/aegis/vault/VaultFile.java:65

            throw new RuntimeException(e);
        }
    }

    public byte[] toBytes() {
        JSONObject obj = toJson();

        try {
            String string = obj.toString(4);
            return string.getBytes(StandardCharsets.UTF_8);
        } catch (JSONException e) {
            throw new RuntimeException(e);
        }
    }

    public static VaultFile fromJson(JSONObject obj) throws VaultFileException {
        try {
            if (obj.getInt("version") > VERSION) {
                throw new VaultFileException("unsupported version");
            }

            Header header = Header.fromJson(obj.getJSONObject("header"));
            if (!header.isEmpty()) {
                return new VaultFile(obj.getString("db"), header);
            }

            return new VaultFile(obj.getJSONObject("db"), header);
        } catch (JSONException e) {
            throw new VaultFileException(e);
        }
    }

    public static VaultFile fromBytes(byte[] data) throws VaultFileException {
        try {
            JSONObject obj = new JSONObject(new String(data, StandardCharsets.UTF_8));
            return VaultFile.fromJson(obj);
        } catch (JSONException e) {

View on GitHub (pinned to d6f4e5925a)