HMCL-dev/HMCL · error · IllegalArgumentException

Invalid game instance id:

Error message

Invalid game instance id: 

What it means

GameInstanceID's compact constructor validates the id string with isValid(id) and throws IllegalArgumentException when it is not a valid instance id. The library enforces identifier rules (e.g. no illegal characters) so ids are safe to map to directory names. The message includes the offending id value (here shown with an empty/absent id).

Solutions

1. Validate the string with GameInstanceID.isValid(id) before constructing
2. Trim/require a non-empty id from user input or JSON before parsing
3. Sanitize or reject ids with illegal characters per isValid's rules
4. Fix the source JSON so the id field is present and well-formed

Example fix

// before
GameInstanceID id = new GameInstanceID(json.get("id").getAsString()); // may be ""
// after
String raw = json.get("id").getAsString().trim();
if (!GameInstanceID.isValid(raw)) throw new JsonParseException("bad id");
GameInstanceID id = new GameInstanceID(raw);

String raw = input == null ? "" : input.trim();
if (!GameInstanceID.isValid(raw)) throw new IllegalArgumentException("Invalid instance id: " + raw);
GameInstanceID id = new GameInstanceID(raw);

static boolean isSafeId(String s) {
    return s != null && !s.isBlank() && GameInstanceID.isValid(s.trim());
}

try { id = new GameInstanceID(raw); }
catch (IllegalArgumentException e) { id = null; LOG.warning(e.getMessage()); }

When it happens

Trigger: new GameInstanceID("") or null/blank string; constructing ids from raw user input or parsed JSON without validation; ids containing path separators or reserved characters rejected by isValid.

Common situations: Empty 'id' field in a version/instance JSON; user submitted an empty name; code passing an untrimmed string of whitespace; deserialization feeding arbitrary strings into the constructor.

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

• Theme background opacity must be between 0 and 1:
• Theme packs cannot reference built-in wallpaper
• ${messagePrefix}${value}
• "File " + file + " is not a valid mod file."
• "File '" + file + "' is not a resource pack"

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/game/GameInstanceID.java:59

    /// Returns whether `id` is a non-blank instance path segment.
    ///
    /// @param id the candidate id
    /// @return whether the id satisfies the repository-independent safety requirements
    public static boolean isValid(String id) {
        return !id.isBlank()
                && !id.equals(".")
                && !id.equals("..")
                && !id.contains("/")
                && !id.contains("\\");
    }

    /// Creates a validated instance id.
    ///
    /// @throws IllegalArgumentException if `id` is not valid
    public GameInstanceID {
        if (!isValid(id)) {
            throw new IllegalArgumentException("Invalid game instance id: " + id);
        }
    }

    /// {@inheritDoc}
    @Override
    public int compareTo(GameInstanceID that) {
        return this.id.compareTo(that.id);
    }

    /// Returns the instance id string.
    ///
    /// @return the value supplied to the constructor
    @Override
    public String toString() {
        return id;
    }

    /// Serializes nullable instance ids as JSON strings.

View on GitHub (pinned to 24702dc5a0)