HMCL-dev/HMCL · error · IOException

Failed to remove instance before restoring backup:

Error message

Failed to remove instance before restoring backup: 

What it means

ModpackUpdateTask.postExecute() throws IOException when it cannot delete the existing instance directory from disk before copying the backup over it. Restoring a backup requires a clean instance root; if removeInstanceFromDisk fails, the restore is aborted to avoid mixing old and new files.

Solutions

1. Close any running Minecraft/launcher processes using the instance, then retry the update
2. Manually delete the instance directory and retry the restore/update
3. Check and fix filesystem permissions on the instances folder
4. Exclude the HMCL instances directory from antivirus real-time scanning

Example fix

// before (locked by running game)
repository.removeInstanceFromDisk(instance.getId()) // false -> IOException
// after
// stop the game first, or pre-clean:
FileUtils.deleteDirectory(instance.getInstanceRoot());

if (Files.exists(instanceRoot) && !isDirectoryWritable(instanceRoot)) { /* abort before update */ }

try { task.run(); } catch (IOException e) { if (e.getMessage().startsWith("Failed to remove instance")) { /* prompt user to close the game / free the directory, then retry */ } }

When it happens

Trigger: Updating/restoring a modpack instance where removeInstanceFromDisk(instance.getId()) returns false - typically because files are locked, read-only, or partially undeletable on the filesystem.

Common situations: Windows file locks (game or launcher still holding files in the instance), permission issues on the instance directory, antivirus locking mods. Note the message concatenates the instance ID, so the trailing text shows which instance failed.

Related errors

• Cannot export a background directory as a theme-pack asset
• Theme background image does not exist
• Instance directory does not exist
• Primary JAR source is not a regular file
• Not a valid world directory

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/modpack/ModpackUpdateTask.java:95

    /// Requests post-execution cleanup or rollback after the update task terminates.
    ///
    /// @return `true`
    @Override
    public boolean doPostExecute() {
        return true;
    }

    /// Retains the backup after success, or restores it and refreshes the repository after failure.
    @Override
    public void postExecute() throws Exception {
        if (isDependenciesSucceeded()) {
            // Keep backup game version for further repair.
            return;
        }

        // Restore backup
        if (!instance.getRepository().removeInstanceFromDisk(instance.getId())) {
            throw new IOException("Failed to remove instance before restoring backup: " + instance.getId());
        }

        FileUtils.copyDirectory(backupFolder, instance.getInstanceRoot());
        instance.getRepository().refresh();
    }
}

View on GitHub (pinned to 24702dc5a0)