HeapHammer

HeapHammer

Memory leaks in a big modpack usually don't show up until a server has been running for a day or two under real player load, like someone flying around on an Elytra, a mob farm running non-stop, machines cycling. By the time the crash happens, you've lost the context that would tell you which mod caused it.

HeapHammer runs that same kind of load on demand and compresses it into about two minutes. It loads chunks, spawns and removes entities, and places and breaks block entities, using the same code paths a real player would trigger, then checks whether memory came back down afterward or kept climbing. It gives you a straight answer: PASS (memory recovered), PASS (plateau) (it settled after an initial cache warm-up), or SUSPICIOUS (memory keeps growing, cycle after cycle - that's a leak).

It's server-side only. You don't need to tell your players to install anything.

What it's built to catch

• Minimap and land-claim mods that keep chunk data after the chunk unloads
• Entity-tracking or damage-indicator mods that don't clean up after mobs despawn
• Tech mods whose machines don't unregister properly when broken
• The kind of leak that only appears when two specific mods are running together, which is usually the hardest to find

You don't need to configure anything mod-specific. It works against whatever's installed because it's exercising the vanilla server, not the mods directly.

Safe to run on a live server

It only touches its own test chunks and entities — never a player's builds or the world spawn. Everything it does is budgeted to a maximum of 15ms per tick, so it won't cause lag or trip your watchdog. If you want to stop a test early, /hh stop or /hh cleanup clears everything immediately.

Using it - Quick Start

Drop the jar in your server's mods folder, then from the console or in-game as an operator:

/hh doctor
/hh run chunks --iterations=5 --batch=10 --radius=8 --strategy=spiral
/hh report show last

If you're chasing down a leak after adding a new mod, run it before and after, then compare the two with /hh report diff, and it'll show you which one changed the numbers.

Other commands: hh status, hh stop, hh cleanup, hh replay <run-id>, hh diagnostics histogram, hh diagnostics heapdump. Everything requires operator level 2 or higher, and it also works with Fabric Permissions API or LuckPerms if you're using either.

It's been tested with 86 automated tests, and against a real dedicated server: a clean install measured 0.75 MB of retained memory per cycle (no false alarm), while a version with a deliberately seeded leak measured 10.56 MB per cycle. It also caught a leak that only showed up when two specific mods were run together — the kind that's easy to miss by testing mods one at a time.

Full Command List

Supported versions

Forge: 1.7.10, 1.12.2. Fabric: 1.16.5, 1.18.2, 1.19.2, 1.20.1, 1.21.1, 1.21.4. NeoForge: 1.21.1.

License: LGPL-3.0.