No More Pose Crash

## PoseStack Guardian

**Stops the “Pose stack not empty” crash dead in its tracks.**

If your modpack uses Pehkui (entity scaling) alongside mods with custom
entity renderers (AzureLib, GeckoLib, Artifacts, Ice and Fire, etc), you’ve
probably hit random disconnects with this error:

`java.lang.IllegalStateException: Pose stack not empty`

This is a known, multi-year-old compatibility issue reported repeatedly
against Pehkui. PoseStack Guardian detects the unbalanced render state
right before it would crash your game and safely corrects it — no more
disconnects.

### Features
– Automatic detection & correction, zero configuration
– Lightweight, client-side only
– Minimal logging (won’t spam your console)

### This is a workaround, not a root-cause fix
The underlying bug is in how Pehkui’s render hooks interact with certain
custom entity renderers. This mod treats the *symptom* (the crash) safely
without touching the actual conflicting mods. See full disclaimer on the
Modrinth page / GitHub repo.

### Requirements
– Fabric Loader
– Minecraft 1.21.1
– Client-side only (safe on servers too, just won’t do anything server-side)

Support
Found a case where this doesn’t work? Open an issue with your latest.log
and mod list.

## Disclaimer

**This mod is a workaround, not an official fix.**

• It does not fix bugs inside Pehkui or any other mod. It intercepts a
    specific crash symptom (unbalanced render transform stack) and corrects
    it safely at the last possible moment, before it would otherwise crash
    your game.
  – It was built and tested against one specific, well-documented crash
    signature (`Pose stack not empty` originating from Pehkui’s entity
    render hooks). It is not a general-purpose fix for all possible
    causes of this exception — if your crash comes from a different mod
    interaction, this mod may not catch it.
  – There is a small chance of a cosmetic, single-frame visual glitch
    (e.g. an entity’s scale/rotation looking very briefly “off”) in the exact
    frame where the correction happens. This is expected — the alternative
    is a full crash/disconnect, which this mod trades for a negligible,
    usually imperceptible visual blip.
  – This mod does not modify, patch, or redistribute any code from Pehkui or
    any other third-party mod. It only observes and corrects Minecraft’s own
    render transform stack via standard Fabric Mixin hooks.
  – Use at your own discretion. The author is not responsible for any issues
    arising from use of this mod in combination with other mods. Always keep
    backups of your world/server before adding new mods.
  – If you are the maintainer of Pehkui (or another mod) and believe this
    mod’s existence points to something you’d like to fix upstream, please
    reach out — this mod would happily become obsolete in favor of an
    official fix.

## Roadmap / Ideas for future development

– Config option to toggle between “silent auto-fix” (current default) and
  “log-only / detection mode” (old debug-only behavior), for people who
  want to diagnose their own mod conflicts without the auto-fix masking
  them.
– Per-mod attribution in logs — automatically parse the stack trace and
  print just the mod ID responsible (e.g. “Detected leak from: pehkui”),
  instead of a raw Java stack trace, so non-technical users can
  immediately tell which mod is involved.
– Broader detection coverage — currently targets one specific injection
  point known to catch the Pehkui + custom-renderer case. Investigate
  whether the same technique can be generalized to catch unbalanced pose
  stacks from other sources too.
– Metrics/telemetry (opt-in only) — anonymous, opt-in count of how often
  the auto-fix triggers and which mod it traces back to, to help build a
  public list of known-conflicting mod combinations.
– 1.20.x / 1.21.x version range support — currently built and tested only
  for 1.21.1. Backport/forward-port once the core approach is confirmed
  stable long-term.
– Quilt-specific testing — should work since it’s built on Fabric Loader
  APIs, but not yet explicitly tested on Quilt.
– Reduce reliance on manually-verified Yarn method names for the
  injection target — investigate a more mapping-resilient way to target
  the exact check point across Minecraft/Yarn version bumps.

If you hit a case this mod doesn’t catch, please open an issue with your log — it directly
helps prioritize the roadmap above.