Troubleshooting¶

Organised by symptom. Messages are quoted as the launcher shows them, so you can search this page for the text on your screen.

Xol is pre-release software, and much of it has not yet run on real Windows or macOS hardware (Supported versions). If your problem is not here, export a support log and write to contact@xol.dev.

Installing¶

macOS blocks the app¶

macOS says that it cannot verify Xol, or cannot check it for malicious software, and offers no Open button.

The build is not notarized, so Gatekeeper asks once. On macOS 15 and later: System Settings ▸ Privacy & Security ▸ Open Anyway. On older versions: Control-click Xol in Applications and choose Open. Full steps on Install on macOS.

If you were not given the installer by the Xol project, do not approve it.

Xol is running from a temporary read-only copy¶

"macOS is running Xol from a temporary read-only copy. Quit Xol, drag it into your Applications folder with Finder, and start it from there; after that it updates by itself."

This is macOS App Translocation: a downloaded app that is started from the folder it arrived in runs from a random read-only location. Xol works, but cannot replace itself, so updates fall back to opening the disk image.

1. Quit Xol.
2. In Finder, drag Xol into Applications. The move has to be made with Finder.
3. Start Xol from Applications.

Related messages: "Xol is running straight from the disk image…" (drag it to Applications and eject the image) and "Xol cannot write to …" (move Xol to a folder you own). See Updates.

Windows protected your PC¶

SmartScreen shows this because the installer is not signed with a code-signing certificate. Choose More info, then Run anyway. See Install on Windows.

If you were not given the installer by the Xol project, do not run it.

Two Xol entries in Windows' installed apps¶

The application identifier changed after 0.2.0, so an installation that started with 0.2.0 can keep a second uninstall entry. Both point at the same data folder. Removing the older entry does not touch your instances.

Apple Silicon and Rosetta¶

Minecraft 1.8.9 and 1.7.10 use Java 8 with LWJGL 2, for which Mojang publishes no arm64 build. On Apple Silicon, Xol therefore runs Mojang's x64 Java through Rosetta 2, exactly as Mojang's launcher does. The launcher itself is a native arm64 app; only the game's Java is translated.

If Rosetta 2 is not installed, the game's Java cannot start. Install it once in Terminal:

softwareupdate --install-rosetta --agree-to-license

While the game runs, the dock names the runtime, for example "jre-legacy mac-os — no arm64 build of this runtime; x64 runtime via Rosetta 2".

This path has not yet been tested on Apple Silicon hardware. The x64 build of the launcher was started under Rosetta on an automated arm64 build machine; Minecraft was not.

Starting Xol¶

"Xol could not start"¶

The launcher could not load its own state. The panel carries the reason. If it mentions the settings file, see the next item. Otherwise, reset the launcher settings and write in with the message.

"Settings were reset"¶

Nothing is lost. The previous file is next to launcher.json as launcher.json.bak-<number>. A single bad field does not cause this; it falls back to its default on its own.

"Xol is still starting. Try again in a moment."¶

You pressed something before the profile manifest had loaded. Wait a second.

Signing in¶

Application ID not approved¶

"Minecraft services rejected this launcher's application ID. The app registration must be approved by Mojang", titled "Sign-in did not complete".

Expected for now. Mojang has not yet approved Xol's application ID, and until it does nobody can complete sign-in. It is not about your account, and there is nothing to change on your side. See Sign-in and accounts.

"Sign-in is not available in this build"¶

"Microsoft sign-in is not configured: no application (client) ID." The build was packaged without an application ID. Ask for a current build.

No Xbox profile¶

"This Microsoft account has no Xbox profile yet. Create one, then sign in again." Create the profile once at xbox.com with the same Microsoft account, then sign in again.

Child account¶

"This is a child account. An adult must add it to a Microsoft family before it can play." An adult adds the account to a family group at account.microsoft.com/family. Microsoft's family settings then decide whether the child account may sign in to third-party applications.

"This account needs adult verification on the Xbox website." Complete the verification at xbox.com.

Region not supported¶

"Xbox Live is not available in this account's country/region." This comes from Xbox Live. Xol cannot work around it.

The account does not own the game¶

"This Microsoft account does not own Minecraft: Java Edition." Sign in with the account that bought the game. If the account owns it but has never chosen a player name: "This account owns Minecraft but has not chosen a player name yet. Set one at minecraft.net, then sign in again."

The browser did not open, or nothing happens¶

The dock reads "Finish signing in in your browser". If no page opened, press Cancel and try again, and check that your system has a default browser. The launcher opens the page through the operating system; it has no built-in browser and no other sign-in method in its interface yet. The browser step times out after five minutes ("Sign-in timed out. Try again.").

"A sign-in is already in progress. Finish it in your browser, or cancel it first." Only one sign-in runs at a time. Press Cancel in the dock, or Cancel sign-in in the account menu.

No secure credential storage¶

"Secure credential storage is unavailable on this system, so Xol will not save a sign-in." Xol refuses to write tokens to disk in plain text. Keychain on macOS and DPAPI on Windows are part of the system, so on those systems this points at a damaged user profile or keychain.

All sign-in messages are listed on Sign-in and accounts.

Installing and launching the game¶

"Could not reach the download servers"¶

"Could not reach the download servers. Check your internet connection and try again — versions that are already installed still launch offline." Check your connection, a firewall or a proxy. The launcher needs HTTPS access to Mojang's servers, maven.minecraftforge.net and, for the 1.7.10 profiles with performance mods, cdn.modrinth.com. Try again resumes; files already downloaded and verified are skipped.

A file did not match its checksum¶

"A downloaded file did not match its expected checksum, so it was discarded. Try again; if it keeps happening the download server is serving a bad file." Usually a broken transfer or a filtering proxy that rewrites downloads. Try again, or try another network. If it persists, report which file; do not work around it by copying files in by hand.

"bundled component … failed its integrity check; reinstall Xol"¶

A file inside the launcher itself is damaged. Reinstall Xol from the installer you were given. Your instances are not affected.

"Incompatible mod in this instance"¶

"Incompatible mod in this instance: (conflicts with …). Move it out of the mods folder or use Repair." A mod you added conflicts with one of the profile's components, for example OptiFine or FastCraft in a profile that contains Hodgepodge. Open Settings ▸ Instance ▸ Open folder ▸ Instance folder, move the file out of mods, and press Play again. The check goes by file name.

The instance belongs to another profile¶

"instance "…" belongs to profile …; clone it or choose another instance". Pick the right instance in Settings ▸ Instance, or clone the one you want. See Instances.

Custom Java problems¶

Unless you have a reason, leave the field empty. Xol then uses the exact runtime Mojang ships for the version.

"JVM argument not permitted"¶

The flag loads code or redirects the JVM (-javaagent, -agentlib, -agentpath, -Xbootclasspath, -cp, -classpath, -jar, -Djava.library.path=, -Djava.class.path=). Remove it. See Launch options.

"Update required" instead of Play¶

A release was marked mandatory inside its signed record. Install the update from the banner. See Mandatory updates.

Minecraft crashed¶

The launcher shows "Minecraft crashed", with the exit code and whether the game wrote a crash report.

1. Open crash report, if there is one, and read the first lines. A mod named there is the usual cause.
2. If you added mods, move them out of the instance's mods folder and try again.
3. Run Settings ▸ Instance ▸ Repair.
4. Try the default memory (Use recommended) and clear any extra JVM arguments.
5. Still crashing: Export support log and write in. With diagnostics on you can also Send this crash report….

Black screen, fullscreen and graphics problems¶

Xol's own material contains no known issues of this kind, because the game has not yet been run through Xol on Windows or macOS or on a real graphics card. There is nothing specific to recommend beyond the general steps: start windowed (Settings ▸ Game ▸ Start in fullscreen off), choose the Balanced preset, remove added mods, and send a support log. Reports of this kind are especially useful right now.

Low frame rate¶

Try the Maximum FPS preset (what it changes), check that memory is at the recommended value, and close other heavy programs. Xol makes no performance claims: nothing has been benchmarked on real hardware, and Xol 1.8.9 ships no optimization of its own yet. On 1.8.9 you can add OptiFine.

In game¶

Right Shift does nothing¶

• The key opens settings only in a world with no other screen open. On the title screen and pause menu use the Xol button in the top left corner.
• Check Options ▸ Controls ▸ Xol ▸ Open Xol settings; the key may be rebound or in conflict with another binding.
• Only the Xol 1.8.9 and Xol 1.7.10 profiles contain the client. The Forge and OptiFine profiles have no Xol button and no HUD.

The HUD is gone¶

The HUD hides with the vanilla HUD: while F1 hides the interface and while the F3 screen is open. Otherwise check that the modules are switched on; only FPS is on by default. A module with nothing to show draws nothing (no potion effects, no armor).

Coordinates do not show on a server¶

On 1.8.9 the module hides itself when reduced debug info is on, which a server can set. That is intended. See Coordinates.

Client settings were reset¶

If xol/config.json cannot be read, the client starts with defaults and renames the bad file to config.json.invalid-<number> in the same folder. It is never deleted.

The zoom key cannot be set¶

Capturing a key in the settings screen has not yet been exercised in a running game. As a workaround, set modules.zoom.settings.key in the client settings file while the game is closed, and please report it.

Updates¶

All update messages, with causes and fixes, are on Updates. The most common:

OptiFine¶

Every rejection message is listed on OptiFine. The most common:

Access key¶

Settings ▸ Service ▸ Xol access key shows one of six states.

Messages while saving a key:

A refused key never stops you playing what is installed. It pauses updates, remote profile data and crash reports. Keys are personal; do not share them.

Offline¶

Installed instances keep launching in both cases, as long as your saved Minecraft session is still valid (it lasts up to a day and cannot be renewed without a connection). Installing a new version needs the download servers, which are separate from the Xol service. There is no offline or cracked mode. Details on Offline behaviour.

Still stuck¶

Export a support log, then write to contact@xol.dev with what you did, what you expected and what happened.