HMCL-dev/HMCL · error · IllegalArgumentException

Instance

Error message

Instance

What it means

Thrown by the ServerModpackRemoteInstallTask constructor when an update was requested (updateTarget != null) but the target instance has no modpack configuration file, i.e. it is not a Server modpack instance. Only instances originally installed from a server modpack can be remotely updated.

Solutions

  1. Install the server modpack as a new instance (updateTarget = null) instead of updating.
  2. Select the instance that was originally installed from a Server modpack.
  3. If the configuration file was lost, reinstall the modpack.

Example fix

// before: update on non-modpack instance
new ServerModpackRemoteInstallTask(depMgr, vanillaInstanceId, manifest, updateTarget);
// after: fresh install
new ServerModpackRemoteInstallTask(depMgr, newInstanceId, manifest, 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 ServerModpackRemoteInstallTask(depMgr, instanceId, manifest, updateTarget);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Instance ")) {
        // install as a new instance instead
    }
}

Prevention

When it happens

Trigger: Constructing ServerModpackRemoteInstallTask with non-null updateTarget for an instanceId whose modpack configuration file does not exist in the repository layout.

Common situations: Attempting a server modpack update against a vanilla or non-modpack instance; wrong instance selected in the update dialog; the instance's modpack configuration was deleted.

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/fa042a002484bec9. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/server/ServerModpackRemoteInstallTask.java:102

    /// @param instanceId        the target instance id
    /// @param updateTarget      the existing instance selecting update mode, or `null` for install
    /// @throws IllegalArgumentException if an update target has no compatible configuration
    /// @throws IllegalStateException    if the target cannot be reserved, an update target is not
    ///                                  the exact published object, or another draft is open
    private ServerModpackRemoteInstallTask(
            DefaultDependencyManager dependencyManager,
            ServerModpackManifest manifest,
            GameInstanceID instanceId,
            @Nullable DefaultGameInstance updateTarget) {
        this.instanceId = instanceId;
        this.updateTarget = updateTarget;
        this.dependency = dependencyManager;
        this.repository = dependencyManager.getGameRepository();
        this.manifest = manifest;

        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.");

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

                if (config == null || !MODPACK_TYPE.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);
        });

        try (GameBuilder builder = this.updateTarget == null
                ? dependencyManager.newGameBuilder(instanceId)

View on GitHub (pinned to 24702dc5a0)