HMCL-dev/HMCL · error · NoSuchGameInstanceException

${id}

Error message

${id}

What it means

DefaultGameRepositorySnapshot.getRegistered looks up an instance by GameInstanceID in its registry and throws NoSuchGameInstanceException when the id is not registered. It is the strict accessor behind getInstance; use hasInstance first if absence is expected. The exception message is the instance id string.

Solutions

1. Call hasInstance(id) (or list registered ids) before getRegistered to confirm existence
2. Re-scan/reload the repository so newly added instances are registered
3. Correct the instance id in the calling configuration or code
4. Create the missing instance if it was expected to exist

Example fix

// before
DefaultGameInstance inst = snapshot.getRegistered(id); // throws if absent
// after
if (snapshot.hasInstance(id)) {
    DefaultGameInstance inst = snapshot.getRegistered(id);
} else {
    inst = createOrSkip(id);
}

if (!snapshot.hasInstance(id)) { /* handle absence: create, skip, or report */ }

Optional<DefaultGameInstance> findRegistered(DefaultGameRepositorySnapshot s, GameInstanceID id) {
    return s.hasInstance(id) ? Optional.of(s.getRegistered(id)) : Optional.empty();
}

try { inst = snapshot.getRegistered(id); }
catch (NoSuchGameInstanceException e) { inst = null; LOG.warning("Unknown instance: " + e.getMessage()); }

When it happens

Trigger: Calling getInstance/getRegistered with an id that was never added to the repository, or one that was removed; passing an id parsed from stale config or an old snapshot.

Common situations: Typo or wrong case in the instance id in settings; referencing an instance after the user deleted it; using a GameInstanceID from a different repository instance; deserialized ids from outdated saves.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• ${inheritsFrom}
• Unsupported icon file:
• Installed theme pack does not contain theme:

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/game/DefaultGameRepositorySnapshot.java:106

    /// Returns the instance with the given id.
    ///
    /// @param id the instance id
    /// @return the instance, or `null` when absent
    public @Nullable DefaultGameInstance get(GameInstanceID id) {
        return instances.get(id);
    }

    /// Returns the registered instance with the given id.
    ///
    /// @param id the instance id
    /// @return the registered instance
    /// @throws NoSuchGameInstanceException if the instance is absent
    public DefaultGameInstance getRegistered(GameInstanceID id) throws NoSuchGameInstanceException {
        DefaultGameInstance instance = instances.get(id);
        if (instance != null) {
            return instance;
        }
        throw new NoSuchGameInstanceException(id);
    }

    /// {@inheritDoc}
    @Override
    public boolean hasInstance(GameInstanceID instanceId) {
        return instances.containsKey(instanceId);
    }

    /// {@inheritDoc}
    @Override
    public DefaultGameInstance getInstance(GameInstanceID instanceId) throws NoSuchGameInstanceException {
        return getRegistered(instanceId);
    }

    /// {@inheritDoc}
    @Override
    public @Nullable DefaultGameInstance findInstance(GameInstanceID instanceId) {
        return instances.get(instanceId);

View on GitHub (pinned to 24702dc5a0)