Troubleshooting Guide

If clicking play results in no response or the game window immediately closes, check the following steps:

• Background process check: If an active Minecraft process is already running in the background (already_running), a new instance will not launch. Click Stop on the launcher home screen or end the stranded process via Windows Task Manager.
• Memory (RAM) allocation: Allocating too little RAM (under 2 GB) or more than 75% of your total system RAM can prevent the Java Virtual Machine from launching. Enable Automatic RAM in profile settings or adjust the slider to a recommended amount.
• Mod conflicts: If recently added mods have conflicting APIs or versions, the startup sequence may hang. Open Performance > Troubleshooter to disable suspected mods and try again.

If Windows SmartScreen or Windows Defender displays an alert when launching Kepler, follow these instructions:

• Why the warning appears: Kepler Client is an active development project and early releases are not yet signed with a commercial digital code-signing certificate (unsigned). The blue Windows protected your PC screen shown by Windows Defender SmartScreen does not mean the application is malicious; it simply indicates that the executable has not yet established broad reputation.
• Steps to proceed past SmartScreen: Click the More info link directly beneath the warning message. Then click the Run anyway button that appears in the lower-right corner to start the launcher.
• Adding a Windows Defender exclusion for the Kepler folder: To prevent real-time protection from mistakenly locking launcher files, you can add an exclusion:
  1. Open Windows Security from the Start menu.
  2. Select Virus & threat protection.
  3. Under Virus & threat protection settings, click Manage settings.
  4. Scroll down to the Exclusions section and click Add or remove exclusions.
  5. Click Add an exclusion, choose Folder, and select your Kepler installation directory.

Kepler Client automatically manages Java runtimes and does not require manual configuration under normal conditions.

• Automatic Java management: Kepler automatically determines the exact Java version required by your profile's Minecraft release using Mojang's official version manifest, and downloads it directly from official sources. You do not need to install Java manually.
• What to do if the download fails: Temporary network drops or firewall rules may interrupt the download.
  1. Check your internet connection and confirm your security software does not block official Mojang endpoints.
  2. Open Performance > Java in the launcher and click Auto-detect/download Java to restart the process.
  3. If you have a matching Java runtime already installed locally (Java 21 for Minecraft 1.20.5+ and 1.21.x, or Java 17 for 1.18–1.20.4), you can manually select the Java binary (javaw.exe) in profile settings.

OpenGL errors, driver timeouts, or blank windows on launch can usually be resolved with the following steps:

• Update graphics drivers: The vast majority of render-phase crashes stem from outdated GPU drivers. Download and install the latest stable driver directly from the official NVIDIA, AMD, or Intel support websites.
• Test without shaders: Shader packs consume heavy GPU resources and may encounter compatibility issues with certain driver versions. If the game crashes upon entering a world, turn shaders off in Video Settings and test with vanilla rendering.
• Laptops with dual GPUs: Windows may default to the integrated processor graphics (iGPU). Open Windows Graphics Settings and ensure Kepler and javaw.exe are explicitly assigned to your high-performance dedicated graphics card.

If a mod file you added does not appear inside Minecraft or its mod menu, verify these compatibility criteria:

• Fabric Loader requirement: Kepler Client runs on the Fabric mod loader. Verify that the mod you downloaded is compiled for Fabric; Forge or NeoForge-only mods will not load in a Fabric environment.
• Matching Minecraft version: The mod file must strictly match your profile's Minecraft version (for example, a mod designed for 1.21.x will not load in a 1.20.x profile). Searching through the launcher's built-in Modrinth browser automatically ensures version compatibility.
• Companion dependencies: Many Fabric mods require helper libraries such as Fabric API to load. Check the mod documentation to confirm that all required companion libraries are enabled in your profile.

If you encounter an unresolvable crash, you can review diagnostic logs and submit a report:

• Launcher crash report view: When the game terminates unexpectedly, the process supervisor captures the exit code and stdout/stderr logs. Navigate to Performance > Troubleshooter to see the root cause and identified mod conflicts.
• Privacy masking: Clicking Copy report or Share log automatically scrubs your system username and private file paths from the text.
• Reaching support: Copy the sanitized report and visit our Support page to contact us or submit feedback.