Troubleshooting¶

Organized by symptom. Most 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. It has been lightly tested on an Apple Silicon Mac and not yet on Windows or an Intel Mac (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. The launcher itself is a native arm64 app. This is only about the game's Java.

The default is a native Apple Silicon Java 8, downloaded from Azul, with Mojang's Intel Java through Rosetta 2 as the automatic fallback. Settings ▸ Java ▸ Java runtime for 1.7 / 1.8 chooses between the two. See Apple Silicon.

Rosetta 2 is needed whenever the Intel runtime is used: for the fallback and for the Intel (Rosetta 2) choice. If it is not installed, that Java cannot start. Install it once in Terminal:

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

While the game runs, the dock names the runtime. It ends in "no arm64 build of this runtime; x64 runtime via Rosetta 2" for the Intel runtime, or in "native Apple Silicon, no Rosetta" for the native one.

"Minecraft did not start with the Apple Silicon Java runtime…"¶

"Minecraft did not start with the Apple Silicon Java runtime, so Xol started it again with the Intel runtime (Rosetta). This profile will keep using the Intel runtime; Repair puts it back to automatic."

On Apple Silicon Macs only. The native runtime did not open a game window within 90 seconds, exited before it did, or could not be downloaded and checked. Xol started the same instance again through Rosetta 2, and the game you are looking at is that second start. Nothing is broken, and the instance keeps using the Intel runtime while the setting is on Automatic.

• To try the native runtime again, run Settings ▸ Instance ▸ Repair, or choose Apple Silicon (arm64) in Settings ▸ Java.
• The reason is recorded. Export a support log and look for the line "instance last ran on". It reads, for example, "rosetta-x64 (the Apple Silicon runtime was tried and fell back: no game window after 90s)". Please send it to contact@xol.dev.
• If the game did not start at all, install Rosetta 2 as described above. The fallback needs it.

Starting Xol¶

"Xol could not start"¶

The launcher could not load its own state. The panel gives 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¶

A panel titled "Sign-in did not complete" says that Minecraft services do not accept this launcher's application ID yet, because Mojang has to approve it first, and that nothing is wrong with your account.

This is expected for now. Mojang has not yet approved Xol's application ID, and until it does nobody can complete sign-in. There is nothing to change on your side, and nothing was saved. 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. Apart from the temporary test sign-in of development builds, it has no other sign-in method. 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. DPAPI is part of Windows, so on Windows this points at a damaged user profile. macOS builds do not use a secure store. They keep the sign-in in a file only your user account can open, so this message does not appear there.

"Please sign in again" after updating on macOS¶

macOS builds no longer use the Keychain, so they do not ask for your Mac password. A sign-in that Xol 0.2.3 or older saved in the Keychain is removed once, and the panel says so. Sign in again. See Sign-in and accounts.

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

Installing and launching the game¶

"Could not reach the download servers"¶

The panel says the download servers could not be reached, asks you to check your internet connection and try again, and notes that versions 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 Xol 1.7.10, cdn.modrinth.com. On an Apple Silicon Mac the native runtime also needs cdn.azul.com, github.com and the GitHub file host it redirects to; if those cannot be reached, Xol falls back to the Intel runtime. 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." This usually means 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 jar in Xol's own mods folder conflicts with one of the profile's components, for example FastCraft in Xol 1.7.10. Xol normally moves jars you put there into my-mods by itself, so this only happens when a file of the same name is already in my-mods. Open the instance folder (Open folder ▸ Instance folder), move the file out of mods, and press Play again. The check goes by file name.

My mods are not loaded¶

Your own mods load only while the Forge mods add-on is on for that Minecraft version. When jars sit in your mods folder while it is off, the main screen says so and offers Turn on Forge mods. Settings ▸ Instance ▸ Mods marks each of your jars "yours, loaded" or "yours, not loaded". A file with a comma in its name cannot be loaded by Forge. Rename it. See Forge mods.

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 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, whether the game wrote a crash report, and the last lines before the crash. If Xol recognizes the cause, the panel explains it and may offer one change as a button, such as Try again with more memory or Start without OptiFine. Nothing changes until you press it, and the game does not start by itself afterwards.

1. Open crash report, if there is one, and read the first lines. A mod named there is the usual cause.
2. If you load your own mods, switch Forge mods off 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. Copy for support puts a short summary on the clipboard. With diagnostics on you can also Send this crash report….

Black screen, fullscreen and graphics problems¶

Xol lists no known issues of this kind, because the game has not been run through Xol on Windows or on a wide range of graphics cards. There is nothing specific to recommend beyond the general steps: start windowed (Settings ▸ Game ▸ Start in fullscreen off), choose the Balanced preset, switch the add-ons off, 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. The OptiFine add-on is available on both versions, and Xol has not measured its effect either.

Low frame rate on an Apple Silicon Mac¶

The default on an Apple Silicon Mac is a native Java. Whether that raises the frame rate is not known. It has only been measured on a machine without a graphics card, where it started the game 3.4 to 4.2 times faster and showed no frame-rate gain. What to try, in this order:

1. Check which runtime the game used. While it runs, the dock names it. If the line ends in "x64 runtime via Rosetta 2", or shows the message about the Intel runtime, the instance fell back or is set to Intel. See the message above.
2. In Options ▸ Video Settings, check that Max Framerate is Unlimited and VSync is off. New instances start that way, and a value you set yourself is never overwritten.
3. Measure instead of guessing. Run the same world with Java runtime for 1.7 / 1.8 on Intel (Rosetta 2) and then on Apple Silicon (arm64), with the frame counter on, and compare the two results: Compare the two yourself. Keep whichever is faster on your Mac.
4. If the native runtime is slower or misbehaves, choose Intel (Rosetta 2).

Either way, the two results and your Mac model are useful to the project: contact@xol.dev.

In game¶

Right Shift does nothing¶

• Right Shift opens the Xol menu in a world. On the title screen use Xol settings. On the pause menu use the small 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.

The menus look different, or I want the vanilla menus back¶

The title screen, the server list, the pause menu and the connect screens are drawn in Xol's look. To get the standard Minecraft menus back, open the Xol settings, expand Menu theme and switch Themed menus off. It applies from the next menu you open. To keep the look but stop the fireflies or snow, set Background animation to Off.

Your servers are not affected either way. The list is the game's own servers.dat. If the menus are vanilla although Themed menus is on, either another mod has put its own screen there, which Xol leaves alone, or the theme switched itself off after an error. The game log then contains "Xol menu theme disabled for this session". See Menu theme.

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 in the Xol menu that the modules are switched on. A module with nothing to show draws nothing, for example with no potion effects or no armor.

Coordinates do not show on a server¶

On 1.8.9 the module hides the position 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.

Updates¶

Updates download in the background and install when you close Xol. 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 keys¶

Xol 0.3.1 has no access key setting. Nothing needs a key: installing, playing, updates and crash reports all work without one. If a key was saved by an older version and the service refuses it, updates pause with "Updates are paused: the access key was refused." Write to contact@xol.dev in that case.

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.