HMCL-dev/HMCL · error · IllegalStateException

Offline account configuration malformed.

Error message

Offline account configuration malformed.

What it means

OfflineAccountFactory.fromStorage throws IllegalStateException when the account's stored metadata JSON lacks the "profileName" field. It indicates the persisted account entry is structurally malformed — every offline account must record its profile name in metadata.

Solutions

1. Restore or add the "profileName" field to the account's metadata JSON and reload.
2. Delete the corrupted offline account entry from accounts.json and re-create the account in the launcher.
3. Restore accounts.json from backup or re-login all offline accounts.

Example fix

// before (malformed metadata)
{"uuid":"...","type":"offline"}
// after
{"uuid":"...","type":"offline","profileName":"Steve","profileID":"..."}

if (metadata == null || !metadata.has("profileName")) {
    // treat entry as invalid and skip or recreate it
    return null;
}

boolean isValidOfflineMetadata(JsonObject meta) {
    return meta != null && meta.has("profileName") && !meta.get("profileName").isJsonNull();
}

try {
    OfflineAccount acc = factory.fromStorage(metadata, privateData);
} catch (IllegalStateException e) {
    // remove or rebuild the malformed account entry
    accountStore.remove(metadata.get("uuid").getAsString());
}

When it happens

Trigger: Calling fromStorage(metadata, privateData) where metadata (accounts.json entry) has no "profileName" key, e.g. after manual edits, partial writes, or downgrades from a different account format.

Common situations: Hand-edited or third-party-written accounts.json; crash mid-write truncating the JSON; syncing account files across HMCL versions with differing schemas; importing accounts from other launchers.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Account private data is not an object
• Config is not an object:
• e
• Game directory ID cannot be nil
• Game directory ID cannot be null

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/0129915b09657684. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/auth/offline/OfflineAccountFactory.java:74

        UUID uuid;
        Skin skin;
        if (additionalData != null) {
            data = (AdditionalData) additionalData;
            uuid = data.uuid == null ? getUUIDFromUserName(username) : data.uuid;
            skin = data.skin;
        } else {
            uuid = getUUIDFromUserName(username);
            skin = null;
        }
        return new OfflineAccount(AccountID.generate(), downloader, username, uuid, skin);
    }

    @Override
    public OfflineAccount fromStorage(JsonObject metadata, JsonObject privateData) {
        AccountID accountID = Account.readAccountID(metadata);
        String profileName = JsonUtils.getString(metadata, "profileName");
        if (profileName == null) {
            throw new IllegalStateException("Offline account configuration malformed.");
        }
        String profileIDText = JsonUtils.getString(metadata, "profileID");
        UUID profileID = profileIDText != null
                ? UUIDs.parse(profileIDText)
                : getUUIDFromUserName(profileName);
        Skin skin = Skin.fromStorage(metadata.get("skin") instanceof JsonObject skinObject ? skinObject : null);

        return new OfflineAccount(accountID, downloader, profileName, profileID, skin);
    }

    public static UUID getUUIDFromUserName(String username) {
        return UUID.nameUUIDFromBytes(("OfflinePlayer:" + username).getBytes(UTF_8));
    }

    public static class AdditionalData {
        private final UUID uuid;
        private final Skin skin;

View on GitHub (pinned to 24702dc5a0)