NPC Helper 2/Docs

For Players

Fix problems as a player

Find out why an NPC is missing, invisible, untranslated, or causing warnings, and how to report a problem.

Most problems are explained in the SMAPI log. This page shows how to read it and what the usual causes are.

Read the log#

  1. While the game is running, read the SMAPI console window.
  2. To read it afterwards, open SMAPI-latest.txt in the game's error log folder. On Windows this is %appdata%\StardewValley\ErrorLogs.
  3. Search for NpcHelper, the NPC's name, or the mod's name. Every problem names the mod, the file, and the setting involved.
  4. To ask for help, upload the log at smapi.io/log and share the link.

NPC Helper 2 does not appear in the console#

  • You must start the game through SMAPI.
  • Check that the folder is Mods/NpcHelper and that manifest.json is directly inside it. A doubled folder (Mods/NpcHelper/NpcHelper/...) is the most common mistake.
  • Check that Stardew Valley is 1.6 or later and SMAPI is 4.0 or later.

An NPC mod is not loaded#

  • SMAPI lists mods it skipped and why. Look for the mod's name near the start of the log.
  • The mod needs NPC Helper 2 installed. If it is missing or too old, SMAPI says so.
  • The mod's folder must be directly inside Mods, with manifest.json directly inside the mod's folder.
  • If the mod has an NPC listed in the summary with a problem, the NPC was rejected. The message says which file, line, and setting is wrong. Report it to the mod's author, with your log.

The NPC is not in the Social tab#

  • The author can hide an NPC until you meet them.
  • The NPC may not have been loaded. Check the summary in the SMAPI console.
  • If the NPC is rejected, the log gives the reason. Report it to the mod's author.

The NPC has no image or looks wrong#

  • A message such as No sprite image found means the mod is missing its main image. Report it to the author.
  • Artwork that changes by place or season is chosen by the NPC's current location and the season. Check at a different place or season before reporting it.

An outfit or portrait pack changes nothing#

  • NPC Helper 2 must be version 2.4.3 or later, and the NPC's own mod must be installed. Outfit and portrait packs do not add an NPC.
  • Read the log for the pack's name. A line such as Outfit pack for Rei: sprites Beach_Summer means it was found. If the pack is not listed, it may not be a content pack for NPC Helper 2 (its manifest.json has to name Framework.Mod.NpcHelper), or its folder is not directly inside Mods.
  • A warning that the pack has an NPC that is not loaded means the pack's NPC name does not match any NPC. Check that the NPC's mod is installed and is the one the pack was made for.
  • An outfit is only worn where its name says. Beach_Summer is the beach in summer, winter is winter everywhere, and spring13 is the Egg Festival. Go there before you report a problem. A festival outfit also needs the NPC to be at that festival.
  • Another mod may change the same image. See below.

Two mods change the same image#

Only one image is used for each name, and NPC Helper 2 says which in the log: portraits/Default.png comes from mod 'Zen Portraits', replacing the NPC's own pack, mod 'Anime Portraits' (several mods provide it; the last one in folder order is used). The mod whose folder comes last wins. To use the other one, remove the one you do not want. Outfits and portraits are chosen separately, so they do not conflict with each other.

A portrait is cropped, doubled, blank or missing after installing a portrait pack#

  • The portrait pack and the NPC may use different portrait sizes. A pack that sets its own size is handled by NPC Helper 2. If you see a strange portrait, report it to the pack's author with the log.
  • A log line such as A 2x portrait sheet must be 256 pixels wide and a multiple of 128 pixels high means the pack's image has the wrong size for what its mod.toml says. Report it to the pack's author.
  • If only some expressions look wrong, the pack may not have a face for every expression the NPC uses. Report it to the author.
  • A portrait that the pack does not replace keeps the NPC's own art, so one place may show the old style. That is normal for a pack that replaces only some images.

The NPC disappears while kissing or at the wedding#

The sprite sheet in use has an empty frame for that pose. NPC Helper 2 warns about it in the log and names the frame. Report it to the mod's author. If you installed an outfit pack that replaces the NPC's main sprite, the pack's author is the one to tell. An outfit that is worn in some places does not have its frames checked, so also tell the author if an NPC vanishes only while wearing one.

The NPC is not at a festival#

NPC Helper 2 must be version 2.4.2 or later, and the NPC mod must be made for festivals. An older NPC mod only gives the NPC lines for a festival, and the NPC is not placed there. Update both mods, or tell the NPC mod's author.

A married NPC stands next to the bed at night#

The NPC mod has no sleeping pose for her. This does not break anything. Tell the mod's author, who can add one. See Sleeping.

A translation does not apply#

  1. The game language must match the translation's language.
  2. The NPC mod must be installed as well.
  3. The translation must be installed in a way NPC Helper 2 can find: as a content pack, or as the older kind of translation that goes into the NPC mod's own folder. See Install NPC mods and translations.
  4. Read the NPC Helper 2 summary. It warns when a translation is for an NPC that is not loaded and suggests the NPC it probably meant.
  5. If a translation works but some lines are in English, look for INCOMPLETE TRANSLATION or OUTDATED TRANSLATION in the summary. See below.

Warnings about an incomplete or outdated translation#

When the game starts, NPC Helper 2 compares each translation with its NPC, for every language, and warns when they do not match. The game still runs; the lines that are missing show in the NPC's original language.

  • INCOMPLETE TRANSLATION means the translation lacks some lines the NPC has. The warning gives the number of lines missing and a few of their names.
  • OUTDATED TRANSLATION means the translation or the NPC mod is an old version. It happens when many lines are missing or the translation's files are more than 60 days older than the NPC mod's. The last sentence tells you how many days apart they are and which one is behind.
  • (legacy) means the translation's files were copied by hand into the NPC mod's own folder (for example from a separate download of a language) and the log is naming it as such.
  • A note such as has 2 extra entries the NPC does not have is not a problem. The translator added lines.

To fix it, update the translation and the NPC mod to versions made for each other. If the translation is by a different person than the NPC mod, the translator may not have updated it yet. See Translation checks at startup for the full explanation and examples.

Warnings about a mod's folders#

A warning about a misspelled folder or file (such as NPCs, locale, or Dialogue.toml) is a mistake in the mod. It is not caused by your setup. Report it to the author.

Report a problem#

Include:

  • The NPC Helper 2 version.
  • The SMAPI log link from smapi.io/log.
  • The name and version of the NPC mod.
  • What you expected, and what happened instead.

Do not share your save files or unrelated personal information.

All versions