Troubleshooting

Common Issues

This guide covers the most common issues users encounter with LiquidBounce and how to resolve them.

Before troubleshooting, make sure you’re using the latest version of LiquidBounce and Fabric.

Installation Issues

Game Won’t Start

Minecraft crashes on startup

Symptoms: Game crashes immediately when launching or during the loading screen.Solutions:

Verify Fabric Installation:
- Ensure Fabric loader is installed for the correct Minecraft version
- Download from fabricmc.net
Check Mod Compatibility:
- Remove all mods except LiquidBounce
- If it works, add mods back one by one to find the conflict
Review Crash Logs:
- Check .minecraft/crash-reports/ for crash reports
- Look for error messages mentioning specific mods or missing dependencies
Verify Java Version:
- Minecraft 1.17+ requires Java 17 or higher
- Check your Java version in the launcher settings

Share crash logs on Discord or the forum for community help.

LiquidBounce not appearing in mods list

Symptoms: Mod list doesn’t show LiquidBounce after installation.Solutions:

Verify Installation:
- Confirm the .jar file is in .minecraft/mods/
- Check you’re launching with the Fabric profile, not Vanilla or Forge
Check File Integrity:
- Re-download LiquidBounce from liquidbounce.net
- Ensure the download completed successfully
Version Mismatch:
- Verify LiquidBounce version matches your Minecraft version
- Check the file name for version information
Fabric API Missing:
- Some features require Fabric API
- Install Fabric API in your mods folder

'Incompatible mod set' error

Symptoms: Error message about incompatible mods or missing dependencies.Solutions:

Install Fabric API:

Download from: https://modrinth.com/mod/fabric-api
Place in: .minecraft/mods/

Check Minecraft Version:
- Ensure all mods are for the same Minecraft version
- Remove mods for different versions
Update Dependencies:
- Update Fabric loader to the latest version
- Update other required mods

Installation Steps Not Working

Clean Installation

Remove LiquidBounce from .minecraft/mods/
Delete the LiquidBounce folder from .minecraft/
Reinstall Fabric loader
Download fresh LiquidBounce build
Place in mods folder and launch

Verify Prerequisites

Java 17+ installed
Fabric loader installed
Correct Minecraft version
No conflicting mods

Check Logs

Review .minecraft/logs/latest.log for error messages during startup

Performance Issues

Low FPS / Lag

Disable Visual Modules

Visual modules like ESP, Tracers, and Trails can impact FPS. Disable modules you don’t actively use.

Optimize Settings

Lower Minecraft graphics settings, reduce render distance, and disable fancy graphics.

Install Performance Mods

Add Sodium and Lithium for better performance.

Allocate More RAM

Give Minecraft 2-4GB of RAM through launcher settings (don’t exceed 50% of total RAM).

Detailed Performance Solutions

Step-by-step FPS optimization

Check Resource Usage:
- Open Task Manager (Windows) or Activity Monitor (Mac)
- Monitor CPU and RAM usage while playing

Optimize Java Arguments: Add these JVM arguments in launcher settings:

-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200
-XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC
-XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40
-XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20
-XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4

Disable Heavy Modules:
- ESP modules (especially with many entities)
- Tracers with long lines
- Particle effects
- Animations
Compatible Performance Mods:
- Sodium - Rendering engine
- Lithium - Server/game optimization
- Starlight - Lighting engine
- FerriteCore - Memory optimization

Memory Issues

Don’t allocate more than 4-6GB of RAM unless you have 16GB+ total system memory.

Out of Memory Errors:

Increase allocated RAM in launcher:
- Open launcher settings
- Find JVM Arguments
- Change -Xmx2G to -Xmx4G (or higher)
Close other applications while playing
Check for memory leaks:
- Monitor RAM usage over time
- Restart game periodically

Module Issues

Modules Not Working

Module enabled but not functioning

Common Causes:

Server-Side Detection:
- Many servers detect and block client modifications
- Module may be disabled server-side
Incorrect Settings:
- Review module configuration
- Some modules require specific settings to work
- Reset module to default settings
Conflicting Modules:
- Disable other modules that might conflict
- Test the module in isolation
Version Incompatibility:
- Module may not work on certain Minecraft versions
- Check GitHub issues for known problems

Module keybinds not responding

Solutions:

Check for key conflicts with Minecraft or other mods
Rebind the module to a different key
Use the command instead: .toggle <module>
Verify keybinds are saved in LiquidBounce/binds.json

Module settings reset on restart

Causes & Fixes:

Permissions Issue:
- Check file permissions for LiquidBounce/ folder
- Ensure Minecraft can write to the directory
Corrupted Config:
- Delete settings.json to reset
- Reconfigure modules
Multiple Instances:
- Close all Minecraft instances
- Launch only one instance

Configuration Problems

Settings Not Saving

Check File Permissions

Ensure .minecraft/LiquidBounce/ folder is writable:

Windows: Right-click folder → Properties → Uncheck “Read-only”
Linux/Mac: chmod -R 755 ~/.minecraft/LiquidBounce/

Verify Config Files

Check if these files exist and are not corrupted:

settings.json
binds.json
accounts.json

Reset Configuration

If files are corrupted, delete and let LiquidBounce recreate them:

# Backup first!
cd .minecraft/LiquidBounce/
mkdir backup
cp *.json backup/
rm *.json

Config Import/Export Issues

Imported config not working

Verify JSON syntax is valid
Check version compatibility
Ensure all required files are imported
Try importing individual files instead of folder

Mod Conflicts

Identifying Conflicts

Binary Search Method

Remove half of your mods
Test if issue persists
Repeat with the problematic half
Continue until you find the conflicting mod

Common Conflicts

Other client mods
Mods modifying rendering
Mods changing keybinds
Performance mods (sometimes)

Known Incompatibilities

These mods may conflict with LiquidBounce:

Other hacked clients (never use multiple clients together)
Some shaderpacks (may cause visual glitches)
Outdated optimization mods
Mods that modify Minecraft’s base classes extensively

Debug Mode & Logging

Enabling Debug Output

Access Debug Settings

Look for debug options in LiquidBounce’s settings menu or configuration files.

Review Logs

Check detailed logs in .minecraft/logs/latest.log for debug information.

Console Output

Launch Minecraft from terminal/command prompt to see real-time console output:Windows:

cd %appdata%\.minecraft
java -jar minecraft.jar

Linux/Mac:

cd ~/.minecraft
java -jar minecraft.jar

Understanding Log Files

Where to find logs

Latest log: .minecraft/logs/latest.log
Crash reports: .minecraft/crash-reports/
Debug logs: .minecraft/logs/debug.log (if enabled)

Use mclo.gs to share logs easily with the community.

Reading error messages

Look for these key indicators in logs:

[ERROR] - Critical errors
[WARN] - Warnings (may not be critical)
[FATAL] - Fatal errors causing crashes
Exception or Error - Stack traces showing what went wrong

Focus on the first error that appears, as subsequent errors are often consequences.

Script Issues

Scripts Not Loading

Script file not recognized

Checklist:

File extension is .js
File is in LiquidBounce/scripts/ folder
File name doesn’t contain special characters
File encoding is UTF-8

Script syntax errors

Common Mistakes:

JavaScript syntax errors:
- Missing semicolons
- Mismatched brackets
- Typos in function names
API usage errors:
- Incorrect API calls
- Missing required parameters
- Using deprecated functions

Debugging:

// Add console logging
print("Script loaded!");
print("Variable value: " + myVariable);

Script causes crashes

Check for infinite loops
Verify all API calls are correct
Test with minimal script first
Check console/logs for error messages
Use try-catch blocks:

try {
    // Your code here
} catch (error) {
    print("Error: " + error);
}

Reloading Scripts

Use the reload command to reload scripts without restarting:

.reload

If scripts still don’t load, try:

Fix any syntax errors
Check file permissions
Restart Minecraft
Review logs for error messages

Network Issues

Connection Problems

Can't connect to servers with LiquidBounce

Some servers block known client modifications
Try disabling all modules before connecting
Check if server allows client mods
Verify you’re not using a VPN that’s blocked

Getting kicked/banned from servers

Many servers prohibit client modifications. Respect server rules!

Server has anti-cheat detecting LiquidBounce
Certain modules are being detected
Your actions appear suspicious

Solutions:

Only use on servers that allow it
Disable detectable modules
Use more subtle settings

Still Having Issues?

Getting Help

Discord Support

Join our Discord for real-time troubleshooting help

Forum

Post detailed issues on the forum

GitHub Issues

Report bugs with logs and reproduction steps

FAQ

Check the FAQ for more common questions

When Asking for Help

Provide this information for faster support:

Your Setup:
- Minecraft version
- LiquidBounce version
- Fabric version
- Operating system
- Other mods installed
The Problem:
- What you’re trying to do
- What actually happens
- Error messages (exact text)
- When it started happening
What You’ve Tried:
- Troubleshooting steps already attempted
- Any changes that might have caused it
Logs:
- Latest log file
- Crash report (if applicable)
- Screenshots of errors

Use mclo.gs or pastebin.com to share logs - don’t paste them directly in chat!

Resources

Common Issues

Installation Issues

Game Won’t Start

Installation Steps Not Working

Performance Issues

Low FPS / Lag

Disable Visual Modules

Optimize Settings

Install Performance Mods

Allocate More RAM

Detailed Performance Solutions

Memory Issues

Module Issues

Modules Not Working

Configuration Problems

Settings Not Saving

Config Import/Export Issues

Mod Conflicts

Identifying Conflicts

Binary Search Method

Common Conflicts

Known Incompatibilities

Debug Mode & Logging

Enabling Debug Output

Understanding Log Files

Script Issues

Scripts Not Loading

Reloading Scripts

Network Issues

Connection Problems

Still Having Issues?

Getting Help

Discord Support

Forum

GitHub Issues

FAQ

When Asking for Help

Build docs developers (and LLMs) love

Resources

​Common Issues

​Installation Issues

​Game Won’t Start

​Installation Steps Not Working

​Performance Issues

​Low FPS / Lag

Disable Visual Modules

Optimize Settings

Install Performance Mods

Allocate More RAM

​Detailed Performance Solutions

​Memory Issues

​Module Issues

​Modules Not Working

​Configuration Problems

​Settings Not Saving

​Config Import/Export Issues

​Mod Conflicts

​Identifying Conflicts

Binary Search Method

Common Conflicts

​Known Incompatibilities

​Debug Mode & Logging

​Enabling Debug Output

​Understanding Log Files

​Script Issues

​Scripts Not Loading

​Reloading Scripts

​Network Issues

​Connection Problems

​Still Having Issues?

​Getting Help

Discord Support

Forum

GitHub Issues

FAQ

​When Asking for Help

Build docs developers (and LLMs) love

Common Issues

Installation Issues

Game Won’t Start

Installation Steps Not Working

Performance Issues

Low FPS / Lag

Detailed Performance Solutions

Memory Issues

Module Issues

Modules Not Working

Configuration Problems

Settings Not Saving

Config Import/Export Issues

Mod Conflicts

Identifying Conflicts

Known Incompatibilities

Debug Mode & Logging

Enabling Debug Output

Understanding Log Files

Script Issues

Scripts Not Loading

Reloading Scripts

Network Issues

Connection Problems

Still Having Issues?

Getting Help

When Asking for Help