HMCL-dev/HMCL · critical · AssertionError

This method should not be called, please verify that the…

Error message

This method should not be called, please verify that the HMCL is complete.

What it means

HMCLBoot's EntryPoint is a bootstrap entry point that must never be invoked directly; the real launcher rewrites/replaces it during startup. If main is ever reached, it unconditionally throws an AssertionError telling the user the HMCL installation is likely incomplete or broken.

Solutions

1. Re-download / reinstall the complete official HMCL JAR — the installation is likely incomplete
2. Launch the correct main class (the HMCL application entry point, not the boot stub)
3. Verify the JAR's manifest Main-Class and that the fat JAR contains the full application
4. Rebuild the distribution with the proper bundling step if building from source

Example fix

// before
java -cp HMCL.jar org.jackhuang.hmcl.boot.EntryPoint
// after
java -jar HMCL.jar  # uses the correct Main-Class of the complete distribution

Class<?> mainClass = Class.forName(manifestMainClass);
if (mainClass.getName().equals("org.jackhuang.hmcl.boot.EntryPoint")) {
    throw new IllegalStateException("Installation incomplete: boot stub is the main class");
}

try {
    launchHmcl();
} catch (AssertionError e) {
    if (e.getMessage().contains("HMCL is complete")) {
        LOG.severe("Broken HMCL installation; reinstall the full official jar", e);
    }
}

When it happens

Trigger: Running java -jar HMCL.jar (or -cp) with org.jackhuang.hmcl.boot.EntryPoint (HMCLBoot module) as the main class, so the placeholder main executes instead of the real HMCL entry point.

Common situations: A corrupted or partially extracted HMCL JAR where the launcher stub was not replaced; manually launching the wrong class; a packaging bug where HMCLBoot's manifest main-class leaked into the distribution.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• bad query string
• Cannot find method 'main(String[])' in
• Game manifest inherits from another manifest
• Missing game manifest

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

Appendix: source

Thrown at HMCLBoot/src/main/java/org/jackhuang/hmcl/EntryPoint.java:28

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
package org.jackhuang.hmcl;

/**
 * This is a dummy class and will be overwritten in the shadow jar.
 */
public final class EntryPoint {
    private EntryPoint() {
    }

    public static void main(String[] args) {
        throw new AssertionError("This method should not be called, please verify that the HMCL is complete.");
    }
}

View on GitHub (pinned to 24702dc5a0)