beemdevelopment/Aegis · error · JSONException

Bad UUID format

Error message

Bad UUID format: %s

What it means

IconPack.fromJson parses the icon pack definition (pack.json) and requires the "uuid" field to be a parseable java.util.UUID. If UUID.fromString throws IllegalArgumentException, the JSON is structurally fine but the identifier is malformed, so it is rethrown as a JSONException naming the bad value. This guards against importing icon packs with corrupted or hand-edited metadata.

Solutions

1. Open pack.json and fix the "uuid" field to canonical UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
2. Regenerate the UUID with UUID.randomUUID().toString() and repackage the ZIP
3. Re-download the icon pack from the original source
4. Validate the JSON before import with a quick UUID.fromString check

Example fix

// before
"uuid": "{31d7a1c8-8b3e-4c2f-9a11-b2c4d5e6f708}"
// after
"uuid": "31d7a1c8-8b3e-4c2f-9a11-b2c4d5e6f708"

String uuidString = obj.optString("uuid", "");
try { java.util.UUID.fromString(uuidString); } catch (IllegalArgumentException e) { /* reject pack before import */ }

boolean isValidUuid(String s) {
    return s != null && s.matches("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$");
}

try {
    IconPack pack = IconPack.fromJson(obj);
} catch (JSONException e) {
    Log.w(TAG, "Invalid icon pack definition: " + e.getMessage());
}

When it happens

Trigger: Importing an icon pack whose pack.json has a "uuid" string that is not in canonical 8-4-4-4-12 hex format (missing dashes, wrong length, non-hex characters, or empty).

Common situations: Hand-editing pack.json and typos in the UUID; a pack generator emitting UUIDs in a nonstandard format (e.g. with braces or URN prefix); truncated/corrupted pack.json after a bad ZIP transfer.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Unable to find pack.json in the root of the ZIP file
• Attempted to write outside of the parent directory
• Attempted to write outside of the icon pack directory
• Unable to find relative to the root of the ZIP file
• Invalid number of iterations for PBKDF

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

Appendix: source

Thrown at app/src/main/java/com/beemdevelopment/aegis/icons/IconPack.java:113

            return false;
        }

        IconPack pack = (IconPack) o;
        return super.equals(pack) || (getUUID().equals(pack.getUUID()) && getVersion() == pack.getVersion());
    }

    @Override
    public int hashCode() {
        return Objects.hashCode(_uuid, _version);
    }

    public static IconPack fromJson(JSONObject obj) throws JSONException {
        UUID uuid;
        String uuidString = obj.getString("uuid");
        try {
            uuid = UUID.fromString(uuidString);
        } catch (IllegalArgumentException e) {
            throw new JSONException(String.format("Bad UUID format: %s", uuidString));
        }
        String name = obj.getString("name");
        int version = obj.getInt("version");
        JSONArray array = obj.getJSONArray("icons");

        List<Icon> icons = new ArrayList<>();
        for (int i = 0; i < array.length(); i++) {
            Icon icon = Icon.fromJson(array.getJSONObject(i));
            icons.add(icon);
        }

        return new IconPack(uuid, name, version, icons);
    }

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

View on GitHub (pinned to d6f4e5925a)