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 Hook was garbage collected. A Hook is undone when it is disposed or finalized. If you do not keep a reference (for example new 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 MethodInfo with typeof(T).GetMethod(...) and its DeclaringType.
  • Another hook does not call orig. A hook that runs before yours in the chain and returns without calling orig hides every later hook. Use DetourManager.GetDetourInfo to list the chain and DetourConfig to order your hook earlier.
  • The hook was created with applyByDefault: false. Call Apply().

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 DMDDumpTo switch and inspect the IL.
  • Match instructions robustly (TryGotoNext with several predicates) and remember that ldc.i4 may 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_DMDType works, MONOMOD_DMDTYPE does not.
  • Hexadecimal parsing. Numeric values are tried as hexadecimal first, so 100 becomes 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 AppContext before 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.dll treats MyMod.mm.dll as the output, deletes it, and scans the directory for mods.
  • MonoMod.Patcher --verbose Game.exe Out.exe counts 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.dll are 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 --info or Mono version), the OS and architecture, and the debug log.
  • The README links to the community Discord.