HMCL-dev/HMCL · error · JsonParseException

Missing protected payload member: protection

Error message

Missing protected payload member: protection

What it means

ProtectionMode.fromEnvelope reads the required 'protection' member of a protected-payload JSON envelope and maps it to a ProtectionMode enum value. If the member is absent, it throws JsonParseException because the envelope cannot declare how its payload was protected, so deserialization cannot proceed safely.

Solutions

1. Restore the 'protection' member to the envelope JSON with the correct protection-mode id
2. Regenerate the envelope via the library's own serialization path instead of hand-editing the file
3. Check for schema/version mismatch and upgrade or downgrade the file to the format this HMCL version expects
4. Catch JsonParseException in the caller and fall back to re-creating the payload

Example fix

// before
{"payload":"..."}
// after
{"protection":"none","payload":"..."}

if (envelope == null || !envelope.has("protection")) { throw new IllegalArgumentException("envelope must contain 'protection'"); }

static boolean hasProtection(JsonObject envelope) { return envelope != null && envelope.has("protection") && envelope.get("protection").isJsonPrimitive(); }

try { mode = ProtectionMode.fromEnvelope(envelope); } catch (JsonParseException e) { LOG.warning("Envelope missing/invalid protection member", e); }

When it happens

Trigger: Calling ProtectedPayload reading APIs with a JsonObject that lacks the 'protection' property — e.g. a hand-written or truncated envelope, or JSON produced by an older/newer schema version that renamed or removed the member.

Common situations: Manually editing the settings/config file and deleting the protection field; copying an envelope from another format; schema drift between HMCL versions.

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.

Related errors

• authlib-injectors.json -> urls cannot be null.
• code is null
• profiles is null
• Account private data is not an object
• Game directory ID cannot be null

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/setting/ProtectedPayload.java:339

        /// @return the selected write mode
        static ProtectionMode fromConfiguredId(@Nullable String id) {
            for (ProtectionMode mode : values()) {
                if (mode.id.equals(id)) {
                    return mode;
                }
            }
            return OBFUSCATED_V1;
        }

        /// Reads the protection mode from an envelope.
        ///
        /// @param envelope the envelope object to inspect
        /// @return the protection mode declared by the envelope
        /// @throws JsonParseException if the declared protection mode is unsupported
        static ProtectionMode fromEnvelope(JsonObject envelope) {
            String protection = JsonUtils.getString(envelope, PROPERTY_PROTECTION);
            if (protection == null) {
                throw new JsonParseException("Missing protected payload member: protection");
            }

            for (ProtectionMode mode : values()) {
                if (mode.id.equals(protection)) {
                    return mode;
                }
            }
            throw new JsonParseException("Unsupported protected payload: " + protection);
        }
    }

    /// Reads and reveals a protected JSON payload from an envelope object.
    ///
    /// @param envelope the envelope object to read from
    /// @param payloadType the expected JSON element type
    /// @return the revealed JSON payload
    /// @param <T> the expected JSON element type
    /// @throws JsonParseException if the envelope is malformed or cannot be revealed

View on GitHub (pinned to 24702dc5a0)