HMCL-dev/HMCL · error · IllegalArgumentException

Unsupported icon file:

Error message

Unsupported icon file: 

What it means

Thrown from the McbbsModpackLocalInstallTask constructor when an update (updateTarget != null) is requested but no modpack configuration file (modpack.cfg-style JSON) exists for the instance. An instance without that file was never installed from an Mcbbs modpack, so updating it as one is invalid.

Solutions

1. Pass updateTarget = null to perform a fresh install instead of an update
2. Verify the instanceId refers to an instance actually installed from an Mcbbs modpack
3. Check that modpack.cfg (the modpack configuration file) still exists in the instance directory
4. Reinstall the modpack from scratch into the instance

Example fix

// before (update on non-modpack instance)
new McbbsModpackLocalInstallTask(dm, instanceId, manifest, updateTarget);
// after: install fresh when no config exists
if (Files.notExists(configFile)) updateTarget = null;

Path json = repository.getLayout().getModpackConfigurationFile(instanceId);
if (updateTarget != null && Files.notExists(json))
    updateTarget = null; // fall back to fresh install

boolean isMcbbsInstance = Files.exists(configFile);

try { new McbbsModpackLocalInstallTask(...); } catch (IllegalArgumentException e) { /* fall back to fresh install */ }

When it happens

Trigger: new McbbsModpackLocalInstallTask(..., updateTarget=<non-null>, instanceId=<id>) where repository.getLayout().getModpackConfigurationFile(instanceId) does not exist on disk.

Common situations: Attempting to update an instance installed manually or from a different modpack format; pointing the update task at the wrong instanceId; the configuration file 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

• Missing hmcl.lwjgl-unsafe-agent.version attribute
• Malformed modpack configuration:
• Invalid library path:
• /assets/
• Interrupted while waiting for pending instance writes

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/game/HMCLGameInstance.java:356

            Path file = getInstanceRoot().resolve("icon." + extension);
            if (Files.exists(file)) {
                return file;
            }
        }
        return null;
    }

    /// Replaces this instance's custom icon file.
    ///
    /// Existing supported icon files are removed before `iconFile` is copied.
    ///
    /// @param iconFile the source icon file
    /// @throws IOException              if the icon cannot be copied
    /// @throws IllegalArgumentException if the file extension is unsupported
    public void setIconFile(Path iconFile) throws IOException {
        String extension = FileUtils.getExtension(iconFile).toLowerCase(Locale.ROOT);
        if (!FXUtils.IMAGE_EXTENSIONS.contains(extension)) {
            throw new IllegalArgumentException("Unsupported icon file: " + extension);
        }

        clearIconFiles();
        FileUtils.copyFile(iconFile, getInstanceRoot().resolve("icon." + extension));
        invalidateIconImage();
    }

    /// Deletes all supported custom icon files for this instance.
    ///
    /// Individual deletion failures are logged and do not stop later files from being attempted.
    public void deleteIconFile() {
        clearIconFiles();
        invalidateIconImage();
    }

    private void clearIconFiles() {
        for (String extension : FXUtils.IMAGE_EXTENSIONS) {
            Path file = getInstanceRoot().resolve("icon." + extension);

View on GitHub (pinned to 24702dc5a0)