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:

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?

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

2. Is the entity in the whitelist?

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

3. Is the entity named?

protect-named-entities: true     # Set to false

4. Is the entity tamed?

protect-tamed-entities: true     # Set to false

5. Is the entity in a boat?

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

6. Is the entity from breeding?

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

7. Is the entity stacked?

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

8. Is whitelist-all-mobs enabled?

whitelist-all-mobs: true         # Set to false

9. Is the item in item-whitelist?

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

10. Is player-heads protection enabled?

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

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

2. Enable Name Protection

protect-named-entities: true

Then name important entities with name tags.

3. Enable Extra Protections

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:

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

# 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

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

Solution: Increase specific mob type limit.

3. Check Spawner Limiter

# 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 <player> permission check CLE.clear

Give permission:

/lp user <player> 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 <player> 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

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

2. More Aggressive Clearing

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

3. Lower Mob Limits

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

4. Enable Misc Entity Limiter

# 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

interval: 180                    # Clear more often

2. Lower Entity Limits

max-mobs-per-chunk: 30

3. Allocate More RAM Edit server start script:

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

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

2. Reload Configuration

/lagg reload

3. Check Chunk Mob Count

/lagg chunkfinder

4. Enable Per-Type Limits

per-type-limits:
  enabled: true

Spawner Limiter Issues

Symptoms:

  • Spawners unaffected
  • Still spawning at normal rate

Solutions:

1. Increase Multiplier

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

worlds: []                       # Empty = all worlds

Misc Entity Limiter Not Trimming

** Symptoms:**

  • Too many armor stands/boats
  • Limits not enforced

Solutions:

1. Verify Sweep Settings

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

2. Check Protection Settings

protect:
  named: true                    # May be protecting them

3. Set Actual Limits

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

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

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

rm plugins/ClearLaggEnhanced/clearlagg.db

Restart server (will regenerate).

MySQL Connection Failed

Symptoms:

  • "Could not connect to MySQL"
  • Authentication errors

Solutions:

1. Verify Credentials

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

2. Test Connection

mysql -h localhost -u root -p

3. Create Database

CREATE DATABASE clearlagg;

4. Grant Permissions

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:

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:

  1. Check for tabs (use spaces)
  2. Verify proper indentation
  3. Use YAML Validator

"HikariPool - Exception during pool initialization"

Cause: Database connection failed

Fix:

  1. Check database configuration
  2. Verify MySQL is running
  3. For SQLite, check file permissions

"Entity clearing is disabled"

Cause: Module not enabled

Fix:

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

"No permission"

Cause: Missing permission node

Fix:

/lp user <player> permission set CLE.admin true

Still Having Issues?

Before Reporting

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

How to Report

Include:

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

Where to Report: