Troubleshooting

Common issues and their solutions for ClearLaggEnhanced.

Installation Issues

Plugin Not Loading

Symptoms:

Plugin shows in red in /plugins
Console shows errors during startup
Commands don't work

Solutions:

1. Check Java Version

java -version

Must be Java 17 or higher.

Fix: Upgrade your Java version or hosting plan.

2. Check Console for Errors Look for lines like:

[ERROR] Could not load 'ClearLaggEnhanced.jar'

3. Verify JAR File

Re-download from official source
Check file isn't corrupted
Ensure correct version for your server

4. Check Dependencies

HikariCP might fail to load
SQLite driver issues

Fix: These are auto-included. If failing, report as a bug.

Configuration Not Generating

Symptoms:

No ClearLaggEnhanced folder in plugins
Config files missing

Solutions:

1. Check File Permissions Server must have write access to plugins folder.

Linux:

bash

chmod 755 plugins/

2. Check Disk Space Ensure server has available disk space.

3. Manual Creation Create folder manually:

plugins/ClearLaggEnhanced/

Then restart server.

Configuration Issues

Entities Not Being Cleared

Symptoms:

/lagg clear does nothing
Automatic clearing not working
Specific entities not clearing

Diagnosis Checklist:

1. Is entity clearing enabled?

yaml

# module/entity-clearing/config.yml
enabled: true

2. Is the entity in the whitelist?

yaml

whitelist:
  - "ARMOR_STAND"     # Remove if you want to clear

3. Is the entity named?

yaml

protect-named-entities: true     # Set to false

4. Is the entity tamed?

yaml

protect-tamed-entities: true     # Set to false

5. Is the entity in a boat?

yaml

extra-protections:
  mobs-in-boats: true            # Set to false

6. Is the entity from breeding?

yaml

extra-protections:
  mobs-from-breeding: true       # Set to false

7. Is the entity stacked?

yaml

protect-stacked-entities: false  # If false, should clear

8. Is whitelist-all-mobs enabled?

yaml

whitelist-all-mobs: true         # Set to false

9. Is the item in item-whitelist?

yaml

item-whitelist:
  - "NETHERITE_INGOT"            # Remove if needed

10. Is player-heads protection enabled?

yaml

extra-protections:
  player-heads: true             # Set to false

Important Entities Being Cleared

Symptoms:

Villagers disappearing
Named pets being cleared
Shop armor stands removed

Solutions:

1. Add to Whitelist

yaml

whitelist:
  - "VILLAGER"
  - "ARMOR_STAND"
  - "ITEM_FRAME"

2. Enable Name Protection

yaml

protect-named-entities: true

Then name important entities with name tags.

3. Enable Extra Protections

yaml

extra-protections:
  mobs-in-boats: true
  mobs-from-breeding: true
  modern-showcase: true

4. Use Scoreboard Tags

/tag @e[type=armor_stand,limit=1,sort=nearest] add CLE_PROTECTED

Then ensure protection is enabled:

yaml

misc-entity-limiter:
  protect:
    tags:
      - "CLE_PROTECTED"

Mobs Not Spawning

Symptoms:

Spawners not working
Natural spawns reduced
Mob farms not producing

Diagnosis:

1. Check Mob Limiter

yaml

# module/mob-limiter/config.yml
max-mobs-per-chunk: 50

Is chunk at limit?

/lagg chunkfinder

Solution: Increase limit or clear existing mobs.

2. Check Per-Type Limits

yaml

per-type-limits:
  limits:
    ZOMBIE: 10                   # May be too low

Solution: Increase specific mob type limit.

3. Check Spawner Limiter

yaml

# module/spawner-limiter/config.yml
spawn-delay-multiplier: 2.0

Solution: Lower multiplier or disable module.

Command Issues

Commands Not Working

Symptoms:

"Unknown command" error
Commands have no effect
Permission denied

Solutions:

1. Verify Plugin is Loaded

/plugins

ClearLaggEnhanced should be green.

2. Check Permissions

/lp user  permission check CLE.clear

Give permission:

/lp user  permission set CLE.clear true

3. Try Full Command Instead of /lagg clear, try:

/clearlagenhanced:lagg clear

4. Check for Conflicts Another plugin might be overriding /lagg command.

Admin GUI Not Opening

Symptoms:

/lagg admin shows error
GUI opens but is blank
Items not showing

Solutions:

1. Must Be Player Console cannot open GUIs. Must be executed in-game.

2. Check Permission

/lp user  permission set CLE.admin true

3. Check Inventory Space Player must have empty space (GUI may not override full inventory).

4. Reload Plugin

/lagg reload

Performance Issues

TPS Still Low After Configuration

Symptoms:

TPS below 15
Server still lagging
Entity clearing not helping

Diagnosis Steps:

1. Enable More Modules

yaml

# config.yml
modules:
  entity-clearing: true
  mob-limiter: true
  spawner-limiter: true
  misc-entity-limiter: true

2. More Aggressive Clearing

yaml

# module/entity-clearing/config.yml
interval: 180                    # 3 minutes instead of 5

3. Lower Mob Limits

yaml

# module/mob-limiter/config.yml
max-mobs-per-chunk: 35           # Lower from 50

4. Enable Misc Entity Limiter

yaml

# module/misc-entity-limiter/config.yml
enabled: true
limits-per-chunk:
  ARMOR_STAND: 3
  ITEM_FRAME: 3

5. Check Other Plugins Use /timings or Spark to identify other lag sources.

High Memory Usage

Symptoms:

Memory usage >80%
Server crashes (OutOfMemoryError)
Frequent garbage collection

Solutions:

1. More Aggressive Entity Clearing

yaml

interval: 180                    # Clear more often

2. Lower Entity Limits

yaml

max-mobs-per-chunk: 30

3. Allocate More RAM Edit server start script:

bash

java -Xms4G -Xmx4G -jar server.jar

4. Check for Memory Leaks

Use Spark profiler
Check other plugins
Monitor with /lagg ram

Module-Specific Issues

Mob Limiter Not Working

Symptoms:

Mobs still spawning beyond limit
No effect on spawners

Solutions:

1. Verify Module Enabled

yaml

# module/mob-limiter/config.yml
enabled: true

2. Reload Configuration

/lagg reload

3. Check Chunk Mob Count

/lagg chunkfinder

4. Enable Per-Type Limits

yaml

per-type-limits:
  enabled: true

Spawner Limiter Issues

Symptoms:

Spawners unaffected
Still spawning at normal rate

Solutions:

1. Increase Multiplier

yaml

spawn-delay-multiplier: 2.5      # Higher value

2. Combine with Mob Limiter Both modules work together:

Mob Limiter: Prevents spawns when limit reached
Spawner Limiter: Slows spawn rate

3. Check World Configuration

yaml

worlds: []                       # Empty = all worlds

Misc Entity Limiter Not Trimming

** Symptoms:**

Too many armor stands/boats
Limits not enforced

Solutions:

1. Verify Sweep Settings

yaml

sweep:
  interval-ticks: 100            # Check every 5 seconds
  max-chunks-per-tick: 20

2. Check Protection Settings

yaml

protect:
  named: true                    # May be protecting them

3. Set Actual Limits

yaml

limits-per-chunk:
  ARMOR_STAND: 5                 # Set specific limit
  BOAT: 5

Integration Issues

PlaceholderAPI Not Working

Symptoms:

Placeholders show as literal text
No values displayed

Solutions:

1. Verify PlaceholderAPI Installed

/plugins

2. Check Registration

/papi list

Should show clearlagenhanced.

3. Test Placeholder

/papi parse me %clearlagenhanced_tps%

4. Reload PlaceholderAPI

/papi reload

Stacker Plugin Integration

Symptoms:

Stacked entities being cleared
Protection not working

Solutions:

1. Verify Stacker Plugin Installed Supported: RoseStacker, WildStacker

2. Enable Stack Protection

yaml

protect-stacked-entities: true

3. Check Console Look for messages like:

[ClearLaggEnhanced] Detected RoseStacker integration

4. Restart Server Integration detection happens on startup.

ModernShowcase Not Protected

Symptoms:

Showcase items disappearing
Display cases clearing

Solutions:

1. Enable Protection

yaml

extra-protections:
  modern-showcase: true

2. Verify ModernShowcase Installed

/plugins

3. Reload Configuration

/lagg reload

Database Issues

SQLite Errors

Symptoms:

Console shows SQLite errors
Database locked messages

Solutions:

1. Check File Permissions clearlagg.db must be writable.

2. Stop Other Instances Only one server should access the database.

3. Delete and Regenerate

bash

rm plugins/ClearLaggEnhanced/clearlagg.db

Restart server (will regenerate).

MySQL Connection Failed

Symptoms:

"Could not connect to MySQL"
Authentication errors

Solutions:

1. Verify Credentials

yaml

mysql:
  host: "localhost"              # Correct host?
  port: 3306                     # Correct port?
  database: "clearlagg"          # Database exists?
  username: "root"               # Username correct?
  password: "password"           # Password correct?

2. Test Connection

bash

mysql -h localhost -u root -p

3. Create Database

sql

CREATE DATABASE clearlagg;

4. Grant Permissions

sql

GRANT ALL PRIVILEGES ON clearlagg.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

Folia-Specific Issues

Plugin Not Working on Folia

Symptoms:

Errors about async operations
Features not working properly

Solutions:

1. Verify Folia Support Check plugin.yml:

yaml

folia-supported: true

2. Update to Latest Version Ensure you have the latest ClearLaggEnhanced version.

3. Report Issue If still not working, report on GitHub with:

Folia version
ClearLaggEnhanced version
Full error log

Error Messages

Common Error Messages and Fixes

"Could not load configuration"

Cause: Syntax error in YAML file

Fix:

Check for tabs (use spaces)
Verify proper indentation
Use YAML Validator

"HikariPool - Exception during pool initialization"

Cause: Database connection failed

Fix:

Check database configuration
Verify MySQL is running
For SQLite, check file permissions

"Entity clearing is disabled"

Cause: Module not enabled

Fix:

yaml

# module/entity-clearing/config.yml
enabled: true

"No permission"

Cause: Missing permission node

Fix:

/lp user  permission set CLE.admin true

Still Having Issues?

Before Reporting

Update to latest version
Check console for errors
Try on clean server (test without other plugins)
Read documentation thoroughly
Search existing issues on GitHub

How to Report

Include:

Server version (Paper/Spigot/Folia + MC version)
Plugin version
Full error logs from logs/latest.log
Relevant config sections
Steps to reproduce
Other installed plugins

Where to Report:

GitHub Issues: https://github.com/BusyBee-Development/ClearLaggEnhanced/issues
Discord: Join our server
Modrinth: Plugin page