HMCL-dev/HMCL · error · IllegalArgumentException

Instance

Error message

Instance

What it means

Thrown by the ServerModpackLocalInstallTask constructor when an update was requested (updateTarget != null) but the target instance has no modpack configuration file, meaning it is not a Server modpack instance. HMCL only allows updating instances that were originally installed as server modpacks.

Solutions

  1. Install the modpack as a new instance instead of updating (leave updateTarget null).
  2. Choose the correct instance that was originally installed from a Server modpack.
  3. If the modpack configuration file was deleted, reinstall the modpack rather than updating.

Example fix

// before: updating a non-modpack instance
new ServerModpackLocalInstallTask(depMgr, existingVanillaInstanceId, zipFile, updateTarget);
// after: install fresh (no updateTarget)
new ServerModpackLocalInstallTask(depMgr, newInstanceId, zipFile, null);
Defensive patterns

Strategy: validation

Validate before calling

Path json = repository.getLayout().getModpackConfigurationFile(instanceId);
boolean canUpdate = updateTarget == null || Files.exists(json);

Try / catch

try {
    new ServerModpackLocalInstallTask(depMgr, instanceId, file, updateTarget);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Instance ")) {
        // fall back to fresh install instead of update
    }
}

Prevention

When it happens

Trigger: Constructing ServerModpackLocalInstallTask with a non-null updateTarget for an instanceId whose modpackConfiguration.json does not exist under the repository layout.

Common situations: Trying to apply a server modpack 'update' onto a vanilla/other-provider instance; picking the wrong instance in the modpack-update dialog; instance config was deleted manually.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/server/ServerModpackLocalInstallTask.java:120

    ///                                  the exact published object, or another draft is open
    private ServerModpackLocalInstallTask(
            DefaultDependencyManager dependencyManager,
            Path zipFile,
            Modpack modpack,
            ServerModpackManifest manifest,
            GameInstanceID instanceId,
            @Nullable DefaultGameInstance updateTarget) {
        this.zipFile = zipFile;
        this.modpack = modpack;
        this.manifest = manifest;
        this.instanceId = instanceId;
        this.updateTarget = updateTarget;
        this.repository = dependencyManager.getGameRepository();
        Path run = repository.getLayout().getInstanceRoot(instanceId);

        Path json = repository.getLayout().getModpackConfigurationFile(instanceId);
        if (this.updateTarget != null && Files.notExists(json))
            throw new IllegalArgumentException("Instance " + instanceId + " is not a Server modpack. Cannot update this instance.");

        @Nullable ModpackConfiguration<ServerModpackManifest> config = null;
        try {
            if (this.updateTarget != null && Files.exists(json)) {
                config = JsonUtils.fromJsonFile(json, ModpackConfiguration.typeOf(ServerModpackManifest.class));

                if (config == null || !ServerModpackProvider.INSTANCE.getName().equals(config.getType()))
                    throw new IllegalArgumentException("Instance " + instanceId + " is not a Server modpack. Cannot update this instance.");
            }
        } catch (JsonParseException | IOException ignore) {
        }

        onDone().register(event -> {
            if (this.updateTarget == null && event.isFailed())
                repository.removeInstanceFromDisk(instanceId);
        });

        dependents.add(new ModpackInstallTask<>(zipFile, run, modpack.getEncoding(), Collections.singletonList("/overrides"), any -> true, config).withStage("hmcl.modpack"));

View on GitHub (pinned to 24702dc5a0)