Modding:Player Guide/Troubleshooting

From Stardew Valley Wiki
< Modding:Player Guide
Revision as of 17:27, 21 May 2019 by Pathoschild (talk | contribs) (→‎"Could not load file or assembly 'Microsoft.Xna.*.dll'" or "System.IO.Compression.dll" (Windows only): make section more generic, cover Linux/Mac installer issues too, remove XNA mention since the fixes were for .NET Framework issues)
Jump to navigation Jump to search

Modding:Player Guide/header

Did something go wrong with your game? This is the page for you. (This page isn't only for players who use mods!)

Common fixes

The basics

  1. Try restarting your computer.
  2. Make sure you have Stardew Valley 1.6 or later.
    Click the "?" button on the title screen, and the version will appear in the bottom-left.
  3. If you use SMAPI, make sure you have the latest version of that.
    The SMAPI version is shown at the top of the SMAPI console window.

Reset your content files

Many problems are caused by broken game files (especially if you use XNB mods). You can reset your game files to fix that. SMAPI mods won't be affected.

  1. See instructions for Steam or for GOG Galaxy.
  2. If you use SMAPI on Linux/Mac, reinstall SMAPI to fix the launcher.
more options 
If you don't want to reset all files, you have some other options.
Option 2: create retroactive backup to reset any file
If you installed XNB mods and want to reset one file you know is broken, you can just restore the original file. If you forgot to back it up, here's how to recover the original files without losing your modded ones:
  1. Copy your game's Content folder to Content-modded.
  2. Reset your game files (see instructions for Steam or for GOG Galaxy).
  3. Copy your (now reset) Content folder to Content-backup.
  4. Move Content-modded back to Content.
Now your content files are still modded, but you have a backup of the original files.
Option 3: troubleshoot XNB mods
If you installed XNB mods, you're not sure which caused the problem, and you don't want to remove all your XNB mods, here's how to figure out which one is causing the problem.
  1. Back up any XNB mods you want to keep.
  2. Reset your game files (see instructions for Steam or for GOG Galaxy). Any XNB mods will be removed, but SMAPI mods won't be affected.
  3. If you use SMAPI on Linux/Mac, reinstall SMAPI to fix the launcher.
  4. Launch the game to see if the problem is fixed.
  5. Reinstall your XNB mods one at a time. After each install, test the game to make sure the mod doesn't cause problems.
Caution: XNB mods (which replace your game files directly) are no longer recommended and can cause issues. Resetting your content files will remove XNB mods you installed. After doing so, consider using content packs instead.

Fix common problems

Save disappeared or doesn't load

See Saves#Troubleshooting.

Nothing happens when you launch the game

The game doesn't open when you try to launch it. (If you use Steam, it might show 'running' for a few seconds.) Here are some common fixes:

  1. Restart your computer.
  2. Make sure you have speakers or headphones plugged in. (They can be muted, but the game needs a working audio device.)
  3. If that doesn't fix it, and you play on Windows:
    1. Install (or reinstall) .NET Framework 4.5.2 and XNA Framework 4.0.
    2. Restart your computer.
    3. Launch the game.
  4. If that doesn't fix it:
    1. Install SMAPI (if you don't already have it).
    2. Launch the game.
    3. Ask for help and attach your SMAPI log.

SMAPI files disappear or your antivirus complains

Your antivirus might remove or complain about some SMAPI files. This is based on heuristic detection (for example, SMAPI rewrites mods so they work on your computer, and rewriting files is something malware also does, so your antivirus got suspicious). Antiviruses learn to allow SMAPI after enough users download it, but this resets for each release. SMAPI doesn't have a trojan — you can check by reading the code, decompiling the download, or uploading it to VirusTotal.

If this happens, here's how to fix it:

  1. Temporarily disable your antivirus.
  2. Redownload and install SMAPI.
  3. Add an exception to your antivirus for the Stardew Valley folder (search online for your antivirus name with the words add folder exception for instructions).

Controller doesn't work properly with SMAPI (Steam only)

Common fixes:

  1. Launch the game through Steam.
  2. Windows only: make sure you set the launch options (see part 2 in the Windows install guide), don't add SMAPI as a non-Steam game.
  3. If all else fails, you can use third-party software to add controller support. Suggested software:
last resort on Linux/Mac 

As a last resort on Linux or Mac, you can disable the SMAPI console window to fix this. You won't see update/error alerts unless you check the log, and your game won't launch after a crash until you delete the smapi-internal/StardewModdingAPI.crash.marker file. You should periodically check the log to make sure everything is working correctly. If you really want to do this:

  • Linux:
    1. Find your game folder.
    2. Open the StardewValley file (the one with no file extension) in a text editor.
    3. Remove the entire section under # open SMAPI in terminal (up to the next fi line).
    4. Find this text at the bottom: 
      if [ $? -eq 127 ]; then
   $LAUNCHER --no-terminal
fi

      And change it to this: 

      $LAUNCHER --no-terminal
  • Mac:
    1. Find your game folder.
    2. Open the StardewValley file (the one with no file extension) in a text editor.
    3. Find this text: 
      open -a Terminal ./StardewModdingAPI.bin.osx $@

      And change it to this: 

      ./StardewModdingAPI.bin.osx $@ 2>&1 > /dev/null
  • Windows: disabling the console window isn't possible.

You'll need to repeat this after updating SMAPI.

Game resolution changes when launched with SMAPI (Windows only)

Symptom: everything looks bigger/smaller if you launch the game with SMAPI, than if you launch without it.

That's usually caused by the Windows DPI settings. Common fixes:

  • Right-click on StardewModdingAPI.exe, go to Properties > Compatibility > Change high DPI settings, and make sure both checkboxes are unchecked.
  • If that doesn't fix it: right-click on Stardew Valley.exe and go to Properties > Compatibility > Change high DPI settings. Take note of what options are set (even if they're grayed out), then set the same options for StardewModdingAPI.exe.

Fix specific errors

"SMAPI can't find the game"

  • Make sure you're running StardewModdingAPI.exe in your game folder (see the install instructions).
  • Did you install SMAPI manually (not using the installer)? Make sure you copied the right files: internal/Windows for Windows, or internal/Mono for Linux/Mac.

"Skipped '...' because it doesn't have a manifest.json"

SMAPI couldn't find the manifest.json file for the mod in that folder. That usually means it's not a SMAPI mod, so it won't work from the Mods folder. See that mod's documentation for install instructions.

"missing executable" (Steam only)

Steam can't find the game launcher, usually because your Steam launch options are incorrect. Common fixes:

  • If you want to use SMAPI:
    make sure it's installed and your launch options are correct (see install guide).
  • If you're uninstalling SMAPI:
    1. In Steam, right-click Stardew Valley and choose Properties.
    2. Click the Set Launch Options button.
    3. Make sure the textbox is completely empty.

"looks like Mono isn't installed" (Linux/Mac only)

Mono is a framework needed by the installer and SMAPI to work correctly. Installing Mono and restarting your computer usually fixes this error.

On Mac, it might not work after installing Mono. If so:

  • Enter this command: 
    ln -s /Library/Frameworks/Mono.framework/Versions/Current/bin/mono /usr/local/bin/mono
  • If that shows an error or it still doesn't work, you can install Homebrew and run brew install mono mono-libgdiplus in the Terminal app.

Could not load file or assembly

If the 'file or assembly' starts with System like this: 

FileNotFoundException: Could not load file or assembly 'System.IO.Compression.FileSystem, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' or one of its dependencies.

Then something is wrong with your .NET Framework installation. In most cases, you can fix it by reinstalling .NET Framework 4.5.2 (Windows), mono-complete (Linux), or Mono (MacOS).

In rare cases on Windows only, that won't fix it. Unfortunately that's difficult to resolve since .NET Framework is part of Windows itself. In those cases you may need to perform a Windows reset (you can keep your files), or perform a clean reinstall of Windows. This is drastic, but usually fixes the issue.

Fix other problems

Run the game without SMAPI by launching Stardew Valley.exe (on Windows) or StardewValley-original (on Linux/Mac) in your game folder.

Ask for help

Find your SMAPI log

The SMAPI log has useful info for troubleshooting problems (like your versions, mods, game path, errors, etc).

Here's how to share it:

  1. Find the log file here:
    Platform Path
    Windows %appdata%\StardewValley\ErrorLogs\SMAPI-latest.txt
    (Paste "%appdata%" into the address bar, Windows knows where it is.)
    Linux ~/.config/StardewValley/ErrorLogs/SMAPI-latest.txt
    (The folder is hidden by default. From Files, click Go » Enter Location and enter "~/.config".)
    Mac ~/.config/StardewValley/ErrorLogs/SMAPI-latest.txt
    (The folder is hidden by default. From Finder, click Go » Go to Folder and enter "~/.config".)
  2. Upload the file to log.smapi.io and share the link.

Find help

For help with a mod, the mod author is the best person to ask. These are the best ways to contact them:

  1. the discussion thread linked to on the mod page (if any);
  2. the 'bugs' section on the Nexus mod page (if any);
  3. otherwise contact the author directly (e.g. use the 'Contact' button on the Nexus mod page).

For help with SMAPI, or if you can't ask the mod author, post in this thread or ask the community.

What to include in a bug report

Figuring out why something went wrong for someone else can be tough, so it helps if you include as much information as possible. Here's the most useful information you can give.

  1. Describe your problem:
    • Which mod has an issue?
    • What is the problem? Be as descriptive as possible. (Does the game freeze or close? Does the screen go black? Does nothing at all happen?)
    • What were you doing when it broke? Did you notice a pattern? For example, maybe it always breaks when you do a certain thing.
  2. Describe your context:
    • Do you use a mod manager? If so, which one?
    • Do you play on Linux, Mac, or Windows?
  3. Upload your SMAPI log to log.smapi.io (see instructions on that page), and add a link to your message.
Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Player_Guide/Troubleshooting&oldid=84097"