Modding:Modder Guide/APIs/Logging
Creating SMAPI mods 
- Get started
- Game fundamentals
- Test & troubleshoot
- Release
- API reference
- Basic SMAPI APIs:
- Advanced SMAPI APIs:
- Specific guides
The monitor API, available through this.Monitor in your mod class, mainly lets you write messages to the console window and log file.
Logging
Overview
You can log messages by calling this.Monitor.Log with a string message and a log level. These messages will appear in the SMAPI console and log file.
For example, this code:
this.Monitor.Log("a trace message", LogLevel.Trace);
this.Monitor.Log("a debug message", LogLevel.Debug);
this.Monitor.Log("an info message", LogLevel.Info);
this.Monitor.Log("a warning message", LogLevel.Warn);
this.Monitor.Log("an error message", LogLevel.Error);
will log something like this:
[18:00:00 TRACE Mod Name] a trace message
[18:00:00 DEBUG Mod Name] a debug message
[18:00:00 INFO Mod Name] an info message
[18:00:00 WARN Mod Name] a warning message
[18:00:00 ERROR Mod Name] an error message
Where to Find the Log File
The log file exists in different locations based on your operating system:
Windows (Steam/GOG): %appdata%\StardewValley\ErrorLogs\SMAPI-latest.txt
Windows (Xbox app): %localappdata%\Packages\ConcernedApe.StardewValleyPC_0c8vynj4cqe4e\LocalCache\Roaming\StardewValley\ErrorLogs\SMAPI-latest.txt
macOS: ~/.config/StardewValley/ErrorLogs/SMAPI-latest.txt
Linux: ~/.config/StardewValley/ErrorLogs/SMAPI-latest.txt
Android: Find the SMAPI-latest.txt file in the StardewValley/ErrorLogs folder on your internal storage.
If Stardew Valley crashed, the log file will be named SMAPI-crash.txt instead of SMAPI-latest.txt.
Log levels
The log level is semantic, meaning that the level itself conveys information (a Trace message means something different from an Error message). You should use the log level that's closest to your message's purpose:
| level | purpose |
|---|---|
| Trace | Tracing info intended for developers, usually troubleshooting details that are useful when someone sends you their error log. Trace messages won't appear in the console window by default (unless you have the "SMAPI for developers" version), though they're always written to the log file. |
| Debug | Troubleshooting info that may be relevant to the player. |
| Info | Info relevant to the player. This should be used judiciously. |
| Warn | An issue the player should be aware of. This should be used rarely. |
| Error | A message indicating something went wrong. |
| Alert | Important information to highlight for the player when player action is needed (e.g., new version available). This should be used rarely to avoid alert fatigue. |
Log once
The LogOnce method lets you log a message just like the above, but only once per game launch. For example, you can use it to show a compatibility warning for an API call:
this.Monitor.LogOnce("Some Mod Name used the deprecated X API.", LogLevel.Warn);
Verbose logging
You can have messages appear in the log (and console in the for developers version) only if SMAPI's verbose logging option is enabled. This is meant for diagnostic information that's sometimes needed to troubleshoot, but doesn't need to be logged in most cases. Players can enable verbose logging by editing the smapi-internal/StardewModdingAPI.config.json file.
There are two ways to use it:
// log a TRACE message if verbose logging is enabled
this.Monitor.VerboseLog("This will only appear if verbose logging is enabled.");
// check the verbose option
if (this.Monitor.IsVerbose)
this.Monitor("This will only appear if verbose logging is enabled.", LogLevel.Trace);
Example Log
Here's the start of an example SMAPI-latest.txt log file:
[23:26:19 INFO SMAPI] SMAPI 3.13.4 with Stardew Valley 1.5.6 (build 22018) on Microsoft Windows 10 Pro [23:26:19 INFO SMAPI] Mods go here: C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\Mods [23:26:19 TRACE SMAPI] Log started at 2022-02-25T05:26:19 UTC [23:26:24 DEBUG SMAPI] Waiting for game to launch... [23:26:25 TRACE game] NoFpsCap: This feature is not available [23:26:26 DEBUG SMAPI] Loading mod metadata... [23:26:26 DEBUG SMAPI] Loading mods... [23:26:26 TRACE SMAPI] CJB Cheats Menu (from Mods\CJBCheatsMenu\CJBCheatsMenu.dll)... [23:26:27 TRACE SMAPI] Rewrote CJBCheatsMenu.dll for OS... [23:26:27 TRACE SMAPI] Rewrote CJBCheatsMenu.dll to fix SpriteBatch methods... [23:26:27 TRACE SMAPI] CJB Item Spawner (from Mods\CJBItemSpawner\CJBItemSpawner.dll)... [23:26:27 TRACE SMAPI] Rewrote CJBItemSpawner.dll for OS... [23:26:27 TRACE SMAPI] TestSDVMod (from Mods\ClassLibrary1\ClassLibrary1.dll)... [23:26:27 TRACE SMAPI] Console Commands (from Mods\ConsoleCommands\ConsoleCommands.dll)... [23:26:27 TRACE SMAPI] Error Handler (from Mods\ErrorHandler\ErrorHandler.dll)... [23:26:27 TRACE SMAPI] Detected game patcher in assembly ErrorHandler.dll. [23:26:27 TRACE SMAPI] Save Backup (from Mods\SaveBackup\SaveBackup.dll)... [23:26:27 INFO SMAPI] Loaded 6 mods: [23:26:27 INFO SMAPI] CJB Cheats Menu 1.29.1 by CJBok and Pathoschild | Simple in-game cheats menu! [23:26:27 INFO SMAPI] CJB Item Spawner 2.1.4 by CJBok and Pathoschild | Simple in-game item spawner! [23:26:27 INFO SMAPI] Console Commands 3.13.4 by SMAPI | Adds SMAPI console commands that let you manipulate the game. [23:26:27 INFO SMAPI] Error Handler 3.13.4 by SMAPI | Handles some common vanilla errors to log more useful info or avoid breaking the game. [23:26:27 INFO SMAPI] Save Backup 3.13.4 by SMAPI | Automatically backs up all your saves once per day into its folder.