PatchLib – Bug Fixes, Crash Fixes & Mod Compat

PatchLib is a random assortment of bug fixes, crash fixes and compatibility patches for various mods — Farmer’s Delight, Tom’s Simple Storage, Vampirism, Toxony, Create, Sable, KubeJS, Arclight and more.

I originally built it just to stop the servers I run from crashing. Over time it grew into a proper little library of fixes, and at some point it stopped making sense to keep it to myself — if one of these crashes has cost you a server restart at 2 AM, this is for you.

Patches only run when they are actually needed

This is the part that matters if you maintain a modpack. PatchLib never touches a mod you do not have installed. Before a single patch is applied, it checks:

• Is the target mod installed? If not, the patch is skipped — no errors, no log spam.
• Is the mod version actually affected? Several fixes are bound to the exact versions that carry the bug. Update the mod past it and the patch quietly steps aside instead of fighting the official fix.
• Does another mod already patch this? Known conflicts disable the patch automatically.
• Is this the right side? Client-only fixes are never loaded on a dedicated server, and the Arclight fixes never on a client.
• Is it a diagnostic or an experiment? Those are opt-in and stay off until you switch them on.

Every decision is printed on startup, so you always know what is running:

[PatchLib] --- Patch Status Report (dedicated server) ---
[PatchLib]  compat.create_contraption_collider [...] -> ACTIVE
[PatchLib]  farmersdelight.tag_load_order      [...] -> SKIPPED (target not present)
[PatchLib]  debug.connection_probe             [...] -> DISABLED (by config)
[PatchLib]  patchouli.book_registry_lookup     [...] -> SKIPPED (not loaded on this side)
[PatchLib] --- 5 of 29 patches active ---

Drop it into a pack with none of the target mods and all it does is print that report.

Included fixes

Crash fixes

Arclight / hybrid server fixes

• ClassCastException when modded entities run Villager AI tasks
• NullPointerException in Brain.tick from Arclight’s villager career redirect
• ClassCastException mapping Friends & Foes entities to Bukkit wrappers
• Bucket events: NullPointerException: ... because "position" is null when a mod empties a bucket for a player without a right-click — for example a Supplementaries slingshot shot carrying a water or lava bucket. It crashed the whole server while the projectile ticked. Arclight only records the clicked block during a real right-click; when that is missing or stale, PatchLib now uses the block that actually changes.
• VanillaBackport: startup crash — its ThrownEggMixin finds nothing to inject into in Arclight’s rewritten ThrownEgg.onHit. PatchLib takes that one mixin off and sets the hatched chicken’s variant itself.
• Blueprint: crash on the first structure load — its StructureStart injector no longer matches Arclight’s rewritten placeInChunk. PatchLib disarms only that injector and feeds Blueprint’s repaletters from a spot that still exists.
• Supplementaries cannons: World minecraft:server_projectile_test_level does not have a CraftWorld — the server crashed as soon as a cannon was loaded, fired or aimed by a Plunderer. Supplementaries test-fires each shot in a private test level; Arclight gives such levels no Bukkit world on purpose, but its entity NBT and game event hooks asked for one anyway. Levels without a Bukkit world now get no Bukkit NBT and no game events (nothing in them listens), and real worlds get their Bukkit data and events exactly as before.

These only load when Bukkit classes are present, so they are inert on plain NeoForge. The VanillaBackport, Blueprint and Supplementaries cannon fixes remove exactly one mixin or injector (for the cannons: one of Arclight’s own) and take over its job; they say so in the log when they do.

Compatibility & behaviour fixes

Performance patches

Hot spots found with spark on a Create + Aeronautics (Sable) server with ~350 mods and on a Vampirism server with ~240 mods. Each shortcut returns the same result as the code it replaces. Each patch is pinned to the mod versions it was checked against and skips itself on any other version.

/patchlib perf shows each patch’s state and how often its shortcut was taken. /patchlib perf <patch> on|off switches one at runtime: off runs the original code, so spark can compare both in one session.

Opt-in tools (off by default)

These do not target any particular mod, so they would run in every pack — which is exactly why they stay off until you set them to true in the config:

Operators also get /patchlib testpanic [ticks]: it makes the next physics ticks fail on purpose, so you can prove the Sable safety net works before a real crash does. Heads-up: the first failed tick already starts Sable’s sub-level recovery, which anything flying will notice.

Version-bound patches

A few fixes only apply to the mod versions that actually carry the bug. If your version is newer, PatchLib reports the patch as skipped — that is intended, not a failure:

Everything else applies to any version of its target mod.

Configuration

Every patch has its own toggle in config/patchlib-patches.properties. The file is generated on first launch with one commented entry per patch:

# --- toms_storage ---
# Treats a retired NeoForge BlockCapabilityCache as an empty inventory instead of throwing
# IllegalStateException out of InventoryConnectorBlockEntity ticking
toms_storage.stale_capability_cache=true

# --- debug ---
# Logs every player's connection state once a second (...). Very noisy
# Opt-in: off unless set to true here.
debug.connection_probe=false

If a fix ever conflicts with something, turn off that one line — no need to remove the mod. When you update PatchLib, new patches are added to your existing file and every value you already set is kept.

Sides

PatchLib is a server-side mod, optional on the client. It registers no network packets and no registry entries, so players without it can join your server normally. Installing it on the client as well adds the two client-side fixes on top, plus the two opt-in client tools if you want them.

Requirements

• Minecraft 1.21.1
• NeoForge 21.1+
• No dependencies

Credits

The Farmer’s Delight, Portable Tanks, Copper Age Backport, Subtle Effects, KubeJS and Just Enough Resources fixes are ported from Monkey Patches by iamthemcmaster (LGPL). Thank you!

⚠ Please read before reporting

These patch bugs in other people’s mods. As those mods update, some of these issues will be fixed properly at the source. Where I know the affected version range, PatchLib disables the patch automatically once you update past it — but I cannot predict every future release. If a mod fixes something natively and the patch gets in the way, just set it to false in the config.

Bug reports about the patches themselves are very welcome. Bug reports about the patched mods belong to their authors.