NPC Helper 2/Docs
You are reading the documentation for v2.2.0. Switch to v2.4.0

Help

Troubleshooting

Resolve common NPC Helper 2 installation, content-pack, TOML, schedule, and artwork problems.

NPC Helper 2 reports content issues in the SMAPI console and log. Search for NpcHelper, the pack name, or the NPC's internal name.

NPC does not appear#

  1. Confirm Stardew Valley 1.6 or later and SMAPI 4.0 or later are installed.
  2. Confirm NPC Helper 2 and the content pack are directly inside the game's Mods/ folder.
  3. Check that the pack's manifest.json has ContentPackFor.UniqueID set to Framework.Mod.NpcHelper.
  4. Confirm the NPC file is under the pack's NPCs/ directory and follows the naming rules in Content Pack Structure.
  5. Read the SMAPI log for the exact file, line, field, or rejected value.

A field or table is ignored#

Check spelling and table placement. For example, [Dialogue] is valid but [Dialgue] is not. Use quotes around text values and check that each field is in the right table. Unknown keys and tables are reported so they can be corrected.

The NPC has no sprite or portrait#

  • Check the expected names: sprites/Default.png and portraits/Default.png.
  • Ensure the files are in the correct NPC folder and use PNG format.
  • Verify that the sheet uses the expected frame grid described in Sprites & Portraits.
  • If a variant is missing, the default image is used instead.

The schedule is not working#

  • Check schedule key spelling and use the game's weekday, season, date, and event names.
  • Use a time the game can read: 600–2600 in 10-minute steps, or a supported clock format.
  • Make sure two stops under the same key do not use the same time.
  • Confirm each stop has valid coordinates and, when needed, a valid location name.
  • Remember that more-specific game schedule keys can take priority over a weekday routine.

Dialogue or gifts behave unexpectedly#

  • Verify dialogue keys and special text syntax against the Stardew Valley dialogue reference.
  • Gift categories and spoken gift responses are configured separately: taste lists go in [GiftTastes]; response lines go in [Dialogue].
  • Use a qualified item ID or a valid game item name when a gift is not recognized.

Marriage content is missing#

  • Set [Romance] Marriageable = true.
  • Put engagement, spouse dialogue, and vows in Marriage.toml.
  • Put the spouse routine in [Marriage] in Schedule.toml.
  • Draw the wedding outfit in sprite frames 36–38. See Marriage.

Still stuck?#

Update NPC Helper 2 and SMAPI, reproduce the issue with the intended pack installed, then review the SMAPI log for the first warning or error related to the pack. Include the NPC Helper 2 version and relevant log messages when asking for help; do not share private save data or unrelated personal information.

Report a documentation issueAll versions