# How to Install and Configure ClearLagg on Your Minecraft Server (/docs/minecraft/setup-clearlag)



import { Step, Steps } from 'fumadocs-ui/components/steps';

**ClearLagg** is the most-installed entity-cleanup plugin for Minecraft. It periodically removes ground items (dropped items, XP orbs, projectiles), caps entity counts, and provides commands for emergency cleanup. Combined with mob-spawn limits and view-distance tuning, it's one of the highest-impact lag fixes for survival servers.

> **Note:** The plugin is officially named **ClearLagg** (two g's). Some older guides spell it ClearLag.

Why ClearLagg Matters [#why-clearlagg-matters]

Dropped items don't despawn for **5 minutes** by default. On a busy server with mob farms, item sorters, or active mining, ground items pile up into the thousands within minutes — and every single one gets ticked every game tick.

| Entity type   | Default tick cost                | Common volume                        |
| ------------- | -------------------------------- | ------------------------------------ |
| Dropped item  | Low individually, deadly in bulk | Mob farms produce 100s/minute        |
| XP orb        | Same                             | Same                                 |
| Arrow         | Low                              | Skeleton spawners produce constantly |
| Falling block | Medium                           | TNT explosions, sand farms           |

A single mob farm can drop **TPS from 20 to 14** with just ground item accumulation. ClearLagg fixes this with one config.

Install ClearLagg [#install-clearlagg]

<Steps>
  <Step>
    Download ClearLagg [#download-clearlagg]

    Get the latest from [SpigotMC](https://www.spigotmc.org/resources/clearlagg.68271/). Compatible with Bukkit, Spigot, Paper, Purpur, and Folia.
  </Step>

  <Step>
    Stop the server [#stop-the-server]

    In the [XGamingServer Panel](https://panel.xgamingserver.com), open **Console** and stop your server.
  </Step>

  <Step>
    Upload to plugins/ [#upload-to-plugins]

    Click **Files** in the sidebar and upload `ClearLagg.jar` to `plugins/`.
  </Step>

  <Step>
    Start the server [#start-the-server]

    Start from **Console**. ClearLagg generates `plugins/ClearLagg/config.yml` on first run.
  </Step>

  <Step>
    Verify it loaded [#verify-it-loaded]

    ```
    plugins
    ```

    `ClearLagg` should appear in green. Test:

    ```
    lagg check
    ```

    Output shows current entity counts.
  </Step>
</Steps>

Recommended Configuration [#recommended-configuration]

The defaults are reasonable, but here's a tuned setup for most survival servers. Edit `plugins/ClearLagg/config.yml`:

Auto-Clear Ground Items [#auto-clear-ground-items]

```yaml
auto-removal:
  enabled: true
  interval: 300                # 5 minutes between clears
  warning:
    enabled: true
    seconds-before: 60         # First warning at T-60s
    extra-warnings: [30, 10, 5, 3, 2, 1]
    message: "&6[ClearLagg] &eGround items will be removed in &c%seconds% &eseconds!"
  broadcast-message: "&6[ClearLagg] &eRemoved &c%amount% &eground items"
```

Entity Limits [#entity-limits]

```yaml
limit:
  enabled: true
  per-chunk:
    item: 64
    arrow: 32
    experience_orb: 32
    item_frame: 16
    armor_stand: 16
```

This caps how many of each entity type can exist per chunk. Excess entities are auto-removed.

What to Clear [#what-to-clear]

```yaml
auto-removal:
  filter:
    item: true
    experience_orb: true
    arrow: true
    snowball: true
    egg: true
    splash_potion: true
    item_frame: false      # Don't clear item frames!
    armor_stand: false     # Don't clear armor stands!
    boat: false
    minecart: false
```

> **Critical:** Always set `item_frame: false` and `armor_stand: false`. Players use these for builds and decorations — clearing them is destructive.

Item Merge [#item-merge]

```yaml
merge:
  enabled: true
  radius: 3.0
  merge-on-pickup: true
```

Merges nearby item stacks to reduce entity count without losing items.

Commands [#commands]

| Command               | Permission           | Description                           |
| --------------------- | -------------------- | ------------------------------------- |
| `/lagg check`         | `clearlagg.check`    | Show current entity counts per type   |
| `/lagg clear`         | `clearlagg.clear`    | Manually clear ground items now       |
| `/lagg area <radius>` | `clearlagg.area`     | Clear entities within radius          |
| `/lagg killmobs`      | `clearlagg.killmobs` | Kill all hostile mobs                 |
| `/lagg unloadchunks`  | `clearlagg.unload`   | Unload non-essential chunks           |
| `/lagg gc`            | `clearlagg.gc`       | Trigger Java garbage collection       |
| `/lagg halt`          | `clearlagg.halt`     | Pause all entity spawning temporarily |
| `/lagg reload`        | `clearlagg.reload`   | Reload config                         |

> **Don't grant `/lagg` perms to regular players.** Use it as an admin tool.

Tuning Tips [#tuning-tips]

| Server type            | Recommended interval           |
| ---------------------- | ------------------------------ |
| Survival, \~10 players | 600 (10 min)                   |
| Survival, \~30 players | 300 (5 min)                    |
| Skyblock / island      | 180 (3 min)                    |
| Anarchy / mob farms    | 120 (2 min)                    |
| Build / creative       | 1800 (30 min) — items are rare |
| Minigame lobby         | 60 (1 min)                     |

**Lower interval = more frequent cleanup = better TPS but more "items vanishing" complaints.** Find the balance for your community.

What ClearLagg Does NOT Do [#what-clearlagg-does-not-do]

| Misconception                  | Reality                                                        |
| ------------------------------ | -------------------------------------------------------------- |
| "ClearLagg fixes all lag"      | It only fixes entity lag — not redstone, chunk gen, plugin lag |
| "It clears player inventories" | Never — only ground entities                                   |
| "It clears chest contents"     | Never — only entities, never blocks                            |
| "It removes mob farms"         | No — but it removes the dropped items the farm produces        |
| "It improves chunk generation" | No — use [Chunky](/docs/minecraft/pregenerate-chunks) for that |

For chunk and tick lag, install [Spark](/docs/minecraft/setup-spark) and read [Optimize Server](/docs/minecraft/optimize-server).

Combined Performance Stack [#combined-performance-stack]

ClearLagg works best as part of a complete optimization setup:

1. **ClearLagg** — auto-clear ground items
2. **[FarmControl](https://www.spigotmc.org/resources/farmcontrol.86923/)** — cap mob farms
3. **[Spark](/docs/minecraft/setup-spark)** — find lag sources
4. **[Chunky](/docs/minecraft/pregenerate-chunks)** — pre-generate world
5. **[Aikar's Flags](/docs/minecraft/jvm-flags)** — tune JVM
6. **Lower [view-distance](/docs/minecraft/render-distance)** — reduce tick load

Common Issues [#common-issues]

| Problem                                 | Fix                                                  |
| --------------------------------------- | ---------------------------------------------------- |
| Players complain "my items disappeared" | Lower clear frequency or increase warning time       |
| Item frames cleared by mistake          | Set `item_frame: false` in filter                    |
| Armor stands disappeared                | Set `armor_stand: false` in filter                   |
| Entity limits too low                   | Raise per-chunk caps in `limit:` section             |
| Plugin doesn't load                     | Wrong server type — Bukkit/Spigot/Paper only         |
| Lag continues after install             | ClearLagg only fixes entity lag — profile with Spark |
| Vehicles cleared                        | Set `boat: false` and `minecart: false`              |

Common Mistakes [#common-mistakes]

| Mistake                                                       | Fix                                              |
| ------------------------------------------------------------- | ------------------------------------------------ |
| Clearing item frames or armor stands                          | Always exclude from filter                       |
| Setting interval too low (e.g., 30s)                          | Players hate it — keep at 120+                   |
| Disabling warnings                                            | Always warn — players need time to pick up items |
| Granting `/lagg` to all players                               | Restrict to admin                                |
| Expecting ClearLagg to solve TPS issues from plugins/redstone | Use Spark to find the real cause                 |
| Not using merge feature                                       | Item merging reduces entity count cheaply        |

Related Guides [#related-guides]

* [Optimize Server](/docs/minecraft/optimize-server)
* [Setup Spark](/docs/minecraft/setup-spark)
* [Change Mob Spawn Rate](/docs/minecraft/change-mob-spawn-rate)
* [Server Tick Loop](/docs/minecraft/fix-server-tick-loop)
* [Pre-Generate Chunks](/docs/minecraft/pregenerate-chunks)