MelonLoader Debug Mode is an important feature for both mod developers and advanced users. It increases log detail, exposes internal loading behavior, and allows external debuggers to attach to the game. Debug Mode is commonly used when diagnosing crashes, mod conflicts, loader errors, or while developing and testing mods.
MelonLoader provides two supported ways to enable Debug Mode:
- Using launch options (recommended)
- Editing the configuration file
Both methods achieve the same result, but launch options take priority if both are used.
What Debug Mode Does in MelonLoader
When Debug Mode is enabled, MelonLoader changes how it initializes and logs information.
Key effects of Debug Mode include:
- Much more detailed console output
- Expanded log files saved to disk
- Additional internal loader diagnostics
- Proper runtime setup for attaching external debuggers
- Improved visibility into Harmony patches and mod loading order
Debug Mode is safe to use but should be disabled when not actively troubleshooting or developing.
Method 1: Enabling Debug Mode Using Launch Options (Recommended)
Using launch options is the cleanest and most reliable way to enable Debug Mode. The debug command is applied at game startup and does not permanently modify configuration files.
Step 1: Identify Your Game Launcher
How you add launch options depends on how you start the game.
Steam
- Open Steam
- Right click the game
- Select Properties
- Open the General tab
- Find the Launch Options field
Epic Games Store
- Open Epic Games Launcher
- Go to Settings
- Scroll down to the installed games list
- Expand the game
- Enable Additional Command Line Arguments
Direct Game Executable
- Create a shortcut to the game executable
- Right click the shortcut
- Select Properties
- Use the Target field to add arguments after the executable path
Step 2: Add the Debug Argument
Add the following command exactly as shown:
–melonloader.debug
This single argument enables MelonLoader Debug Mode.
After adding it, launch the game normally.
Optional Advanced Debug Arguments
For deeper troubleshooting or mod development, MelonLoader supports additional debug related arguments.
Capture Unity Player Logs
–melonloader.captureplayerlogs
This forces MelonLoader to capture Unity engine level logs. These logs are very detailed and useful when diagnosing crashes that occur before mods fully load.
Increase Harmony Log Detail
–melonloader.harmonyloglevel
This controls the verbosity of Harmony patch logs. Developers may use values such as Info or Debug depending on their needs.
Launch Debugger Automatically (Il2Cpp Only)
–melonloader.launchdebugger
This starts the dotnet debugger and pauses execution until a debugger attaches. It is used primarily for advanced Il2Cpp debugging.
Suspend Until Debugger Attaches (Mono Only)
–melonloader.debugsuspend
This causes the game to wait at startup until an external debugger such as dnSpy attaches. This is useful for early initialization debugging.
Method 2: Enabling Debug Mode Using the Configuration File
MelonLoader also allows Debug Mode to be enabled permanently through its configuration file. This method is useful if you want Debug Mode to remain active across launches.
Step 1: Locate the Configuration File
- Launch the game once with MelonLoader installed
- Close the game
- Navigate to the game installation directory
- Open the UserData folder
The configuration file is located at:
GameName\UserData\Loader.cfg
Step 2: Edit the Loader.cfg File
- Open Loader.cfg using a plain text editor such as Notepad or VS Code
- Find the section labeled loader
- Locate the debug_mode setting
- Change its value to true
Example configuration:
[loader]
debug_mode = true
Save the file and launch the game.
Important Priority Rule
If Debug Mode is enabled using both methods:
- Launch options always override the configuration file
- Removing the launch argument will restore the configuration file setting
Where to Find Debug Logs
When Debug Mode is active, MelonLoader writes detailed logs to:
GameName\MelonLoader\Logs
These log files are essential when:
- Reporting issues to mod developers
- Requesting support in modding communities
- Diagnosing crashes or failed mod loads
Always share the full log file when asking for help.
Using Debug Mode with External Debuggers
One of the most important purposes of Debug Mode is enabling debugger attachment.
Mono Games
- Supports live debugging using tools such as dnSpy
- Allows breakpoints, stepping through code, and inspecting variables
- debug_suspend is often used during early startup debugging
Il2Cpp Games
- Requires MelonLoader generated proxy assemblies
- launchdebugger is used to wait for debugger attachment
- Debugging is more complex due to native compilation
Debug Mode configures the runtime correctly so that these tools can connect without crashing the game.
Performance and Safety Considerations
Debug Mode increases logging and diagnostic overhead. While generally safe, it can:
- Slightly reduce performance
- Increase load times
- Create very large log files over time
For this reason, Debug Mode should be disabled when not actively needed.
How to Disable Debug Mode
To disable Debug Mode:
- Remove –melonloader.debug from launch options
- Or set debug_mode = false in Loader.cfg
- Restart the game
This returns MelonLoader to normal operation.
Final Summary
MelonLoader Debug Mode is a powerful feature for both developers and advanced users. It enables detailed logging, exposes internal loader behavior, and allows external debuggers to attach correctly. The recommended method is using launch options, while configuration file editing provides a persistent alternative. Debug Mode should be enabled only when needed and disabled afterward to maintain performance and clean logs.
MelonLoader official website:
https://melonloader.pro/
Download MelonLoader:
https://melonloader.pro/download-melonloader/
MelonLoader GitHub:
https://github.com/LavaGang/MelonLoader