HMCL-dev/HMCL · error · JsonParseException

Missing instance id

Error message

Missing instance id

What it means

GameInstanceManifest.fromJson requires an 'id' field; when the parsed JSON has no id it throws JsonParseException('Missing instance id'). The manifest is the source of truth for instance identity, so deserialization cannot proceed without it. The raw JSON is retained on the builder before the check to aid diagnostics.

Solutions

1. Add an 'id' field to the instance manifest JSON and re-parse
2. Check the JSON key spelling/nesting matches what fromJson expects ('id' at top level)
3. Fix the code that produced/saved the manifest so it always writes the id
4. Validate the JSON schema before calling fromJson

Example fix

// before
{ "name": "My Instance" } // no id
// after
{ "id": "my-instance", "name": "My Instance" }

if (!json.has("id") || json.get("id").isJsonNull()) throw new JsonParseException("Missing instance id");
GameInstanceManifest m = GameInstanceManifest.fromJson(json, false);

static boolean hasId(JsonObject json) {
    return json.has("id") && json.get("id") instanceof JsonPrimitive p && !p.getAsString().isBlank();
}

try { m = GameInstanceManifest.fromJson(json, false); }
catch (JsonParseException e) { if (e.getMessage().equals("Missing instance id")) { repairManifest(json); } else throw e; }

When it happens

Trigger: Calling GameInstanceManifest.fromJson on a JsonObject lacking an 'id' member, or the member present but not extracted (e.g. wrong case, wrong nesting, non-string type the parser ignores).

Common situations: Hand-edited or truncated instance.json/version JSON; copying a partial manifest; third-party launcher JSON with a differently named id key; gson stripping an unexpected type.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Theme-pack author must be an object or a string
• Theme-pack manifest is missing themes array
• accountID is missing
• /assets/
• authlib-injectors.json -> urls cannot be null.

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/game/GameInstanceManifest.java:293

                    }
                }
                case "patches" -> {
                    if (value instanceof JsonArray array) {
                        List<GameInstancePatch> list = new ArrayList<>(array.size());
                        for (JsonElement element : array) {
                            if (element instanceof JsonObject object) {
                                list.add(GameInstancePatch.fromJson(object));
                            }
                        }
                        builder.patches = List.copyOf(list);
                    }
                }
            }
        }

        builder.rawJson = json;
        if (builder.id == null) {
            throw new JsonParseException("Missing instance id");
        }

        return builder.toManifest();
    }

    /// Returns whether the manifest is hidden.
    ///
    /// @return whether the manifest is hidden
    public boolean isHidden() {
        return hidden != null && hidden;
    }

    /// Returns whether the manifest is a root manifest.
    ///
    /// @return whether the manifest is a root manifest
    public boolean isRoot() {
        return root != null && root;
    }

View on GitHub (pinned to 24702dc5a0)