Client Mixin Intercept

A server-side mod that automatically intercepts client-side Mixin injections which would otherwise crash the server, allowing previously unstartable mod packs to launch successfully.

模组 Forge 优化修复

介绍

中文介绍正在准备中，下面暂时显示原文。

Introduction

This mod is a compatibility mod designed specifically for server environments (it will not activate on the client side). During server startup, it identifies Mixins that may bring client-side code into the server and cause crashes, intercepting or fine-filtering them while preserving as much of the original mod’s server-side functionality as possible.

However, this mod is not a universal fixer, nor does it replace the need for original mod authors to properly isolate environments at their core.

Issue Classification

Category	Plain Explanation	Handling Method
`DIRECT_CLIENT_TARGET`	The Mixin directly modifies a client-only class, and this injection has actually escalated into a fatal error that would stop startup.	Downgrades the fatal error at Mixin’s official error-handling stage, allowing the server to continue loading.
`CLIENT_REFERENCE`	The target class of the Mixin can load on the server, but its fields, method signatures, or method bodies still reference client-platform classes.	Attempts to remove only the problematic fields/methods and clean up their dependencies; disables the entire Mixin only when localized handling is impossible.

For example, a Mixin targets a normal entity class that exists on the server, but one of its methods calls Minecraft (the client instance) or rendering classes. Disabling the entire Mixin outright is unnecessary — this mod prioritizes filtering only the dangerous parts of the code.

No Blind Blocking of All Client-Related Code

To minimize false positives, this mod respects the mod’s existing environment guards:

The client list in Mixin configurations;
Declared IMixinConfigPlugin in Mixin configs;
@Pseudo annotations;
Common environment annotations and runtime environment checks from Forge, NeoForge, Fabric, or Architectury;
Client targets that Mixin itself can normally skip.

In particular, DIRECT_CLIENT_TARGET is only recorded when a Mixin actually enters the ERROR state in the error handler. Simply having a target class name inside a .client. package, the target not existing on the server, or the Mixin skipping the target normally — none of these will automatically add the mod to the report.

Viewing the Report

The ClientMixinMod.txt file is regenerated on every standalone server startup. Example output:

# Client Mixin Intercept Report / 客户端 Mixin 拦截报告
# Direct client targets / 直接注入客户端类
[DIRECT_CLIENT_TARGET]
example_mod

# Unguarded platform-client references / 未受环境保护的平台客户端引用
[CLIENT_REFERENCE]
another_mod

The file records the mod’s modid, deduplicated and sorted:

Listed under DIRECT_CLIENT_TARGET — the mod triggered a client-target injection that reached the fatal error level, and this mod has intercepted it;
Listed under CLIENT_REFERENCE — the mod’s Mixin contains unguarded platform-client references, which have been filtered at the bytecode level;
The same mod may appear under both categories;
Being listed does not mean the entire mod is written incorrectly, nor that all of its functionality will break — it simply means that at least one Mixin code segment required handling in the current server environment.

Note: False positives are still possible with this mod, although it has passed development testing (on several mod packs with 200+ mods in server environments) with a 100% accuracy rate.