Troubleshooting
This page lists common problems with MonoMod, what causes them, and how to fix them. Entries follow the same pattern: the symptom you see, the cause found in the source, and the fix. Before anything else, turn on logging (see Logging): most RuntimeDetour problems are explained in the debug log.
RuntimeDetour
My Hook Is Never Called
Symptom: The Hook is created without errors, IsApplied is true, but your code never runs.
Causes and fixes:
- The method was inlined. If the JIT inlined the source method into a caller before you hooked it, that caller keeps the inlined copy. Small methods such as property getters are often inlined. Mark methods you own with
[MethodImpl(MethodImplOptions.NoInlining)]; for third-party code, apply hooks as early as possible (before the callers are compiled) or hook the caller instead. - The
Hookwas garbage collected. AHookis undone when it is disposed or finalized. If you do not keep a reference (for examplenew Hook(...);as a statement), it disappears at the next garbage collection. Store it in a field for as long as it should stay active. See Lifetime. - You hooked a different method. A hook on a virtual method hooks that one implementation; an override in a derived class is a separate method. Check the exact
MethodInfowithtypeof(T).GetMethod(...)and itsDeclaringType. - Another hook does not call
orig. A hook that runs before yours in the chain and returns without callingorighides every later hook. UseDetourManager.GetDetourInfoto list the chain andDetourConfigto order your hook earlier. - The hook was created with
applyByDefault: false. CallApply().
ArgumentException: Source Method Is Generic
Symptom: ArgumentException: Source method is generic, generic hooks are not supported.
Cause: RuntimeDetour rejects generic methods and methods on generic types (for Hook, ILHook and their source).
Fix: Hook a non-generic method that calls the generic one, or use an ILHook on such a caller.
ArgumentException: Target Method Is Not Compatible
Symptom: Target method is not compatible with source method or Target method's delegate parameter is not compatible with the source method.
Cause: The hook method's signature does not follow the target signature rules. Common mistakes: forgetting the self parameter for an instance method, self of the wrong type, a value type self that is not ref, or an orig delegate whose parameters differ from the source plus self.
Fix: Write the target as ReturnType Hook(OrigDelegate orig, SelfType self, params...), with orig being a delegate of ReturnType(SelfType self, params...).
ILHook Throws InvalidProgramException
Symptom: Adding an ILHook throws, often InvalidProgramException: Common Language Runtime detected an invalid program, or a later call to the method crashes.
Cause: The manipulator produced invalid IL: unbalanced stack, a branch to a removed instruction, a wrong type on the stack, or a call with the wrong argument count. Because every ILHook on a method is re-applied on fresh IL each time an ILHook is added or removed, a problem can also come from another mod's manipulator, which now sees IL changed by yours.
Fix:
- MonoMod compiles the method while the hook is being added and rolls the hook back if that fails (see Failure and recovery), so the exception points at the hook being added.
- Dump the generated method with the
DMDDumpToswitch and inspect the IL. - Match instructions robustly (
TryGotoNextwith several predicates) and remember thatldc.i4may be any of its short forms. See MoveType and labels for how labels and branches move.
InvalidOperationException: Cycle Detected
Symptom: Applying a hook throws an exception containing Cycle detected, or the log contains Detour 'A' is marked as being both before and after 'B'.
Cause: DetourConfig Before/After lists that cannot all be satisfied. A direct contradiction between two detours only logs a warning; a longer cycle throws. In the current source, the rollback after a cycle does not fully remove the failing node, so later changes to hooks on the same method may keep failing.
Fix: Check the IDs in every Before/After list (remember that Before = ["B"] means "this detour runs before B"). See Conflicts and cycles.
PlatformNotSupportedException or NotImplementedException at First Hook
Symptom: The first detour throws PlatformNotSupportedException (for example CoreCLR version ... is not supported) or NotImplementedException.
Cause: MonoMod.Core has no implementation for the current runtime, OS or architecture. 32-bit ARM, Android, iOS and BSD are not implemented, and CoreCLR versions outside the known list are rejected.
Fix: Use a supported platform (see Supported platforms) or update MonoMod: each new .NET major version needs a new runtime implementation.
Crash or Failure When /tmp Is Not Executable
Symptom: On Linux or macOS, detouring fails when loading a native library, typically on systems that mount /tmp with noexec.
Cause: MonoMod.Core writes a small native helper library into /tmp and loads it.
Fix: Set the HelperDropPath switch (for example MONOMOD_HelperDropPath=/path/to/writable/exec/dir).
MonoMod.Utils
A Switch Has No Effect
Symptom: You set MONOMOD_Something or Switches.SetSwitchValue, but nothing changes.
Causes and fixes:
- Wrong case. Switch names are case-sensitive:
MONOMOD_DMDTypeworks,MONOMOD_DMDTYPEdoes not. - Hexadecimal parsing. Numeric values are tried as hexadecimal first, so
100becomes 256. See Value parsing. - Read too late. Some switches, in particular the logging switches, are read once when the relevant class initializes. Set them as environment variables before starting the process, or with
AppContextbefore touching MonoMod.
DMDType Is Ignored
Symptom: MONOMOD_DMDType=MethodBuilder (or Cecil) has no visible effect.
Cause: A backend that is unavailable on the current target framework is skipped. The MethodBuilder backend only exists in .NET Framework builds and net9+ builds of MonoMod.Utils.
Fix: See Backends and check the log for the generator that was used.
DynamicData Silently Does Nothing
Symptom: Setting a member through DynamicData "works", but the object's real field never changes.
Cause: A name that does not match a field or property (a typo, wrong case) is stored as extra data on the DynamicData object instead of throwing. Overloaded and generic methods are also skipped when methods are collected.
Fix: Check names carefully, or use TryGet to see whether a member exists. See DynamicData.
ModInterop Fields Are Null
Symptom: After typeof(MyImports).ModInterop(), some delegate fields are null, including fields that had a value before.
Cause: Each field without a matching export is reset to null. Exports are matched by name and delegate type.
Fix: Check that the exporting mod was loaded and registered first, and that names and signatures match exactly. Check fields for null before calling them. Registration is not thread-safe, so do it from one thread. See ModInterop.
Tools
Patcher Applies No Mods
Symptom: MonoMod.Patcher runs, writes an output, but none of your patches are in it, or your mod file disappears.
Cause: The meaning of the positional arguments depends on how many arguments there are, options included:
MonoMod.Patcher Game.exe MyMod.mm.dlltreatsMyMod.mm.dllas the output, deletes it, and scans the directory for mods.MonoMod.Patcher --verbose Game.exe Out.execounts three arguments, so it reads mods from the empty range between input and output.- When scanning, only files starting with the input's name minus its extension (keeping the dot, for example
Celeste.) and ending with.mm.dllare picked up.
Fix: Either use the one-argument form with correctly named mods next to the input, or list everything: MonoMod.Patcher Game.exe A.mm.dll B.mm.dll Out.exe. Details: Patcher command line.
The Patcher Executable Is Not Named MonoMod.exe
Symptom: Older guides tell you to run MonoMod.exe, but there is no such file.
Cause: In the current source the patcher's assembly is named MonoMod.Patcher. It is also not packed as a NuGet package, so you build it from source (see Getting the command-line tools).
Fix: Run MonoMod.Patcher (or dotnet MonoMod.Patcher.dll).
Patch Modifiers That Do Not Work as Documented
| Modifier or option | Problem in the current source | Workaround |
|---|---|---|
[MonoModOnPlatform(...)] |
With any platform listed, the item is ignored on every platform. | Use [MonoModIfFlag] with a flag set in MonoModRules. See MonoModOnPlatform. |
MONOMOD_PREVENTINLINE |
Masks the method's implementation flags with &= 0x0100 instead of adding NoInlining, which clears other flags. |
Do not rely on it; add [MethodImpl(MethodImplOptions.NoInlining)] in your patch. |
--uncached |
Sets MONOMOD_RELINKER_CACHED, which nothing reads. |
No effect either way. |
DebugIL --relative, --skip-maxstack, --diff |
Set environment variables with names the generator does not read. | Set MONOMOD_DebugIL_Relative=1 / MONOMOD_DebugIL_SkipMaxStack=1 yourself. See DebugIL. |
HookGen: Delegate Has Already Been Applied
Symptom: ArgumentException: Delegate has already been applied to this method as a hook! when using On. events.
Cause: HookEndpointManager keys hooks by method and delegate, so adding the same delegate to the same event twice throws.
Fix: Subscribe once, or unsubscribe before subscribing again.
HookGen: -= Does Not Remove My Hook
Symptom: On.Ns.Type.Method -= (orig, self) => ...; leaves the hook active.
Cause: Each lambda expression is a new delegate instance, and unknown delegates are ignored by Remove.
Fix: Subscribe a named method or keep the delegate in a variable, and unsubscribe that same delegate. See HookGen.
Getting More Help
- Search the issue tracker and open a bug report with the template, including the MonoMod version, the runtime (
dotnet --infoor Mono version), the OS and architecture, and the debug log. - The README links to the community Discord.