Documentation

Learn how to install and use LiquidBounce with our comprehensive guides

Troubleshooting LiquidLauncher

Try the fixes below first. If none of them help, contact us through our contact page or on our Discord.

Table of Contents


Your LiquidLauncher is outdated and must be reinstalled

LiquidLauncher v0.5.0 and older cannot sign in with Microsoft authentication anymore, because Mojang blocked our login. You can read more in our blog post Microsoft Tried to Ban Us!.

LiquidLauncher v0.6.0 and newer fix this, but the auto updater in v0.5.0 is broken, so it cannot update itself. Many people had no idea why nothing worked anymore, so old launchers now show this error on purpose.

You are affected if the launcher shows Failed to establish connection with LiquidBounce API and the Technical Details box below it mentions:

YOUR-LIQUIDLAUNCHER-IS-OUTDATED-AND-MUST-BE-REINSTALLED-MANUALLY

To fix it:

  1. Download the latest LiquidLauncher from liquidbounce.net/download.
  2. Install it the same way you installed LiquidLauncher the first time. Installing over your current version is fine, there is no need to uninstall it first, and on Linux you simply replace the old AppImage.
  3. Start LiquidLauncher and add your Microsoft account again, since the old sign in method does not exist anymore.

Your settings and already downloaded LiquidBounce versions are kept. From v0.6.0 onwards the launcher updates itself again, so this is a one-time step.

If the same error still appears afterwards, your launcher is up to date and the cause is a different one. Continue with Failed to establish connection with LiquidBounce API.

LiquidLauncher does not show up (Windows)

This happens if you uninstalled Microsoft Edge or used a Windows "debloat" tool. LiquidLauncher needs Edge Webview2 to run, which is part of Windows.

To fix it, download and install Microsoft Webview2. The launcher will show up after that.

LiquidLauncher does not show up (Linux with Wayland)

If you're using Linux with Wayland (especially with NVIDIA graphics), you may encounter this error:

Gdk-Message: Error 71 (Protocol error) dispatching to Wayland display.

This is a known upstream WebKit2GTK issue on Wayland. To fix it, launch LiquidLauncher with the following environment variable:

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./LiquidLauncher

To make this permanent, edit your LiquidLauncher desktop file (usually in ~/.local/share/applications/):

Exec=env WEBKIT_DISABLE_DMABUF_RENDERER=1 /path/to/LiquidLauncher

Alternatively, add this to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export WEBKIT_DISABLE_DMABUF_RENDERER=1

For more information, see this GitHub issue.

LiquidBounce download does not finish (SmartScreen issue)

This is a known bug on Windows 10. We are currently working on a proper fix. For now, please disable Windows Smart Screen to solve the issue. You can do so by following these steps:

  1. Open the start menu and search for Windows Security.
  2. Open the program and select App & browser control.
  3. Click Reputation based protection settings.
  4. Uncheck Check apps and files and SmartScreen for Microsoft Edge.
  5. Restart your computer and try again.

Failed to establish connection with LiquidBounce API

Using Cloudflare WARP

Cloudflare WARP is a free VPN that can fix connection problems with the LiquidBounce API. To set it up:

  1. Download Cloudflare WARP from the official website.
  2. Install the application by following the on-screen instructions.
  3. Once installed, open the Cloudflare WARP application.
  4. Click on the "Connect" button to establish a VPN connection.
  5. After the connection is established, restart LiquidLauncher.

If it still doesn't work with WARP on:

  1. Open the Cloudflare WARP application settings.
  2. Navigate to "Preferences" or "Settings" depending on your operating system.
  3. Enable "WARP+" mode if available or try switching between different WARP modes.
  4. Restart your computer and try launching LiquidLauncher again.

A VPN like WARP gets around network blocks or bad routes that can stop LiquidLauncher from reaching the LiquidBounce API.

Fixing issues with the system's hosts file

Some alternative Minecraft authentication services like TheAltening may make changes to your system's hosts file. These can cause error messages like the following:

  • "The authentication servers are down for maintenance."
  • "The authentication servers are currently not reachable."
  • "Please switch to Mojang mode."
  • "Not authenticated with minecraft.net."
  • It may also prevent LiquidLauncher from working properly ("An error with the client occurred: Connection to https://launchermeta.mojang.com/ failed.").
  • java.net.ConnectException: Connection refused: getsockopt

To reset your hosts file and fix these issues, follow these instructions for your respective operating system.

On Windows

  1. Search for notepad in start menu, right-click it, and run it as an administrator.

  2. Click Yes to allow the program to make changes to your device.

  3. In the Notepad window, click File and then select Open....

  4. Navigate to C:\Windows\System32\drivers\etc\.

  5. Select All Files from the drop down in the bottom right corner of the window.

  6. Open the file called hosts.

  7. Remove all lines containing one of the following words:

  • minecraft
  • mojang
  • microsoft
  • xbox
  • live

  1. Save the file and restart your computer.

The problems should now be resolved.

On macOS and Linux

  1. Open a terminal.
  2. Execute sudo nano /etc/hosts.
  3. Enter your computer's password when prompted.
  4. Move the cursor using the arrow keys and delete all lines containing either mojang or minecraft.
  5. Press Ctrl + O to save and Ctrl + X to exit.
  6. Restart your computer.

The problems should now be resolved.

References

These instructions are based on the ones provided by sparkuniverse.notion.site.


Fixing issues with the DNS server

DNS servers resolve domain names to their corresponding IP address. A misconfigured DNS server can lead to connection issues. We recommend using 1.1.1.1, a DNS server provided by Cloudflare. To set a DNS server, please follow these instructions:

On Windows 11

  1. Go to Settings.
  2. Select Network & internet
  3. Select Wi-Fi or Ethernet depending on your connection.
  4. If you selected Wi-Fi in the previous step, click Properties of [your wifi's name].
  5. Under DNS server assignment, select Edit.
  6. From the drop-down menu, select Manual.
  7. Turn on the IPv4 toggle switch.
  8. Under Preferred DNS, enter 1.1.1.1 and 1.0.0.1.
  9. Hit Save and restart your computer.

On Windows 10, 8 & 7

  1. Open the control panel.
  2. Select Network and Sharing Center.
  3. Click Change adapter settings on the left side of the window.
  4. Double click your current internet connection whether it’s Wi-Fi or Ethernet.
  5. Click Properties in the window that popped up.
  6. Select Internet Protocol Version 4 (TCP/IPv4) from the list under This connection uses the following items.
  7. Press Properties.
  8. Change the radio button to Use the following DNS server addresses.
  9. Enter 1.1.1.1 as preferred DNS and 1.0.0.1 as alternate DNS.
  10. Press OK and restart your computer

On macOS

Please follow this guide provided by Apple.

On Linux

How to change DNS depends on your distribution and desktop environment, so search for a guide that matches yours.