Troubleshooting

Most problems show a message that says what went wrong. Find the message below, or the symptom if there is no message.

Sign-in problems

"XSTS rejected Xbox login. Check if account owns MC"

Minecraft accounts sign in through Xbox Live, even on a computer. This message means Xbox Live refused the account. The number at the end of the message says why:

If there is no code, check that this Microsoft account is the one that owns Minecraft: Java Edition. Many people have two Microsoft accounts and bought the game on the other.

"This account needs to sign in again."

The saved sign-in has expired or was withdrawn, for example after a Microsoft password change. Sign out in the launcher and sign in again. Nothing else is lost; your game folders stay as they are.

"Microsoft sign-in timed out before Breeze received the authorization code."

The Microsoft window was left open too long, or closed before it finished. Start the sign-in again and complete it in one go. If the window never appears, check that no other program is blocking new windows, and that the clock on your computer is right; a wrong clock makes secure sign-ins fail.

Signing in on this website

The website uses a code instead of a pop-up window: it shows a short code and a link to Microsoft's page, microsoft.com/link. Open the link, enter the code and sign in; the website notices by itself once you are done. "This account does not own Minecraft Java Edition." means the account you used has no Java Edition licence.

The game will not start

"No Breeze build for this Minecraft version yet, launching without Breeze features"

The version you chose is not one of the 34 supported versions, for example a snapshot or a release older than 1.17. The game starts with Fabric but without the Breeze menu. Pick a supported version to use Breeze.

"Breeze runtime mod unavailable, launching without Breeze features: …"

The launcher could not fetch the Breeze mod, usually because the Breeze servers could not be reached. Minecraft still starts, without the Breeze menu. Check your internet connection and that nothing (a firewall, an antivirus, a school or work network) blocks api.breezeclient.net, then launch again.

"Breeze needs Fabric Loader …; Fabric offers …"

That Breeze build needs a newer Fabric Loader than Fabric publishes for this Minecraft version. The game starts without Breeze. This clears up when either side publishes an update; try again later, or play a neighbouring version.

Java messages

"No Java runtime is available for this version on this computer"

Mojang does not publish a Java runtime for this Minecraft version on your system, or it could not be downloaded. Check your connection and launch again. On an uncommon system, install the Java version the message names yourself and set JAVA_HOME to it.

"The Java … runtime disappeared before launch. Launch again to reinstall it."

Something removed the Java files, often an antivirus clean-up. Launch again and the launcher downloads them once more.

"Could not reserve enough space for object heap"

Minecraft asked for more memory than your computer could give it. In Config, lower RAM Allocation, or use Auto-Set Recommended RAM. Closing browsers and other large programs helps too.

"Minecraft exited with code … and printed no error."

Minecraft closed without saying why in the launcher. Open the Console page for the full launch log; the lines just before the end usually name the problem, often a mod. Then follow crashes below.

"No game libraries were resolved for this version…"

The downloaded files for that version are incomplete. Reinstall the version from the launcher, as the message says, so it downloads them again.

Crashes

When Minecraft crashes, it writes a crash report. Look in the version folder (.breezeclient/instances/<version>):

• crash-reports has one file per crash, newest last;
• logs/latest.log is the log of the last session.

Most crashes come from a mod. To find which one:

1. Read the crash report's first lines. A mod's name or ID often appears next to "Caused by".
2. If you added mods, turn them all off on the Mods page and launch. If the game starts, turn them back on a few at a time until the crash returns.
3. Check for two copies of the same mod, or two mods that do the same job, such as two minimap mods.
4. Make sure every mod is a Fabric mod for this exact Minecraft version. Forge mods and OptiFine never load on Fabric.

If the crash happens with no extra mods at all, it is ours to fix: send the crash report through a support ticket.

The Breeze menu does not open

• Check the key. Another mod may use Right Shift. Look for Open Breeze Menu in Options, Controls, Key Binds, and give it a free key. The title screen and pause menu also have a Breeze button.
• First start of a web-menu version. On the 20 versions with the web menu, the embedded browser downloads its Chromium files (over 100 MB) the first time the game starts. Until it is ready, the menu may open as Breeze's own screens. Give it a minute, or longer on a slow connection, then open the menu again.
• Launched without Breeze. If the launcher said "launching without Breeze features", the mod is not loaded this time; see The game will not start.

HUD elements in the wrong place or missing

• Open the HUD editor and use Reset on the element, or Reset all.
• Check the element's switch in the HUD editor's side list, and that the module itself is on.
• The Auto Hide HUD module hides Minecraft's own HUD; turn it off if the vanilla hotbar has disappeared.
• F1 hides every HUD, Breeze's included. Press it again.

Cosmetics not showing

• Only players who use Breeze see Breeze cosmetics.
• Other players see a change within about 15 seconds.
• Check the item is equipped on the launcher's Style page or in the in-game Wardrobe, and that you are signed in with the account that owns it.
• A custom cape from the Custom Cape module is only visible to you.

Update problems

"Downloaded update looks incomplete, try again or download from the website."

The update file arrived damaged or cut short. Try again; if it fails twice, download the installer from the download page and install it over the top. Your game folders are kept.

"Update download was cut short, try again."

The connection dropped during the download. Try again.

"Breeze is no longer running from an AppImage, so it cannot update itself."

On Linux, the AppImage updates itself only while it runs as an AppImage. Download the new AppImage from the download page. If you installed the .deb or .rpm, install the new package the same way.

Installing

• Windows says "Windows protected your PC": choose More info, then Run anyway. The installer is not yet signed with a paid certificate.
• macOS will not open the app: System Settings, Privacy & Security, Open Anyway. See macOS install steps.
• Antivirus removed the launcher or Java: restore it from quarantine and add an exception for the Breeze folder. Compare the installer's checksum with the published SHA-256 if you want to be sure the file is genuine.

Low frame rate

• Check that Sodium and the other performance mods are switched on in Mods. Breeze adds them the first time you play a version; if you removed them, pick a Performance Profile in Config to add them again.
• Lower the render distance in Minecraft's video settings; it has the biggest effect.
• Turn on Reduce Launcher GPU Usage and turn off Keep Launcher Open, so the launcher does not compete with the game.
• Shaders cost a lot. Try without them.
• The FPS and System Resources HUD modules show the frame rate, memory and CPU use while you play.

Asking for help

Open a support ticket (sign in first) or ask in the Breeze Discord. Include:

• your system (for example Windows 11, or macOS 14 on an Apple silicon Mac);
• the launcher version, from Config, About;
• the Minecraft version you were playing;
• the exact message, copied rather than retyped;
• for a crash, the crash report or logs/latest.log.

Logs can contain your Minecraft username and the address of the server you were on. Share them in a ticket rather than a public channel if that matters to you.