Troubleshooting

When things don't work. Common cases first, edge cases after, plus how to file a useful bug report at the bottom.

"I don't see anything happen — Stitchwork isn't running"

Check the bottom-left corner of the screen for the Status Overlay — a small badge showing pack and conflict counts. If it's missing, Stitchwork didn't load.

Most common cause: you also have the older mod Patchwork installed. Stitchwork notices and disables itself. You'll see a notice on the main menu:

What's needed for this image: screenshot of the inert-mode toast on the title screen.

To fix: remove Patchwork.dll from BepInEx/plugins/. Note that Architect-Silksong does not require Patchwork and runs fine alongside Stitchwork — only a standalone Patchwork install trips the inert mode.

Other causes:

• BepInEx itself isn't installed. Stitchwork is a BepInEx plugin — without BepInEx 5, it can't load. Check that BepInEx/core/BepInEx.dll exists in your game folder.
• Stitchwork is in the wrong place. Its DLL must sit in a folder one level under BepInEx/plugins/ (recommended name: StitchworkRoot/). The folder name itself doesn't matter — Stitchwork resolves its location from where the DLL loaded — but the DLL can't be loose in plugins/ or buried deeper.
• An exception during startup. Open BepInEx/LogOutput.log and search for Stitchwork. Errors during the plugin's Awake would be there.

"I dropped a sprite PNG in but nothing changed"

A.k.a. "sprite replacement not showing" — the most common new-creator question.

Check the file path

The path matters. Common mistakes:

• Sprite/ instead of Sprites/ — note the s.
• Wrong collection name — it's case-insensitive but must match the in-game collection. Use the Animation tab in the Dev Hub to verify the exact name.
• Wrong material name — same.
• Wrong sprite name — the filename (without .png) must match the sprite name. Idle_0.png and idle_0.png both work; idle 0.png (with space) and idle-0.png (with dash) don't.
• .PNG extension uppercase — usually fine, but case-sensitive filesystems will fail. Use lowercase .png to be safe.

Did the file watcher pick it up?

Stitchwork has hot-reload — file changes are detected and applied within about a second. If your file is in the correct path but the game isn't picking it up:

• Try a scene transition (walk through a door). The scene-load path re-applies replacements unconditionally.
• Try toggling the pack off and on in Pack Manager.
• Check BepInEx/LogOutput.log — look for [Stitchwork] entries near the time you saved the file. You should see a "reload" log line.

Is the sprite ACTUALLY visible right now?

If the character is mid-animation showing a different frame, of course you won't see your replacement until that specific frame plays. Wait until the right frame is on-screen (idle, mid-attack, specific expression).

For Animator-driven sprites that change per-frame, the replacement is applied each time the frame shows.

"Some text is invisible / garbled after a pack apply"

Symptom: applied a skin pack, now main-menu text or save-slot text shows as boxes, gibberish, or is missing entirely.

This is a known issue with skin packs that include certain texture naming patterns (specifically when a pack ships Spritesheets/T2D/font.png or similar — the name matches a font atlas Silksong loads internally). We've shipped multiple fixes; the current build should handle most cases.

If you still see it:

1. Confirm you're on the latest Stitchwork build.
2. Identify the offending pack by disabling packs one at a time.
3. File a bug report with the pack name and what you see (see "Filing a useful bug report" below).

Workaround until fix: rename any T2D PNGs in your pack folder away from generic names like font.png, tex.png, etc.

"Two packs target the same thing — what wins?"

The pack with the higher priority. In the Pack Manager, packs are listed in priority order top-to-bottom. The Pack Manager shows "conflicts" — places where two or more packs target the same asset — and tells you which pack wins.

To change priority: drag-reorder packs in the Pack Manager (or use the up/down arrows next to each pack). After reordering, hit Apply.

The Status Overlay at the bottom of the screen shows total conflict count — useful as a "how messy is my current setup" gauge.

"My pack used to work and now doesn't after I added another pack"

Likely cause: the new pack overrides the same files. Check the conflict count and the Pack Manager's conflicts foldout — it tells you exactly which keys collide.

If the new pack shouldn't be overriding what your pack does, that's a bug in the new pack — its files are mis-named or its scope is broader than intended. Report it to that pack's author.

"The Pack Manager / Dev Hub window is stuck somewhere weird"

If a window is dragged to a position outside the visible screen (e.g. you played at a different resolution and dragged it off-screen), you can usually reset by:

• Edit BepInEx/config/Stitchwork.cfg — look for window-position entries and reset them to 0,0 or delete the lines and restart.
• Some windows reset automatically when the game launches at a new resolution.

If a window's contents are blank (header visible but body empty), and hotkeys stop working, this used to indicate a GUI bug we fixed in the 0505 builds. Update Stitchwork. The fix included a self-healing mechanism — the GUI should recover within a couple of seconds even if something throws.

"Audio replacement plays the wrong audio / cuts off / restarts"

A few separate cases:

• One-shot SFX plays vanilla once, then plays your replacement: this is expected on the very first time a sound fires after your pack is enabled. Stitchwork has to download the replacement asynchronously; the first trigger fires before the load completes. Subsequent triggers use the cached replacement. If it persists past the first trigger, file a bug.
• Music restarts on scene transition: this was a bug fixed in the 0505 builds. Update if you're seeing it.
• Music continues playing the OLD track after a pack switch: also a known case — looped audio doesn't re-fetch the buffer when its AudioClip is reassigned. Stitchwork forces a clean swap (Stop+Play) for looped tracks during pack-apply, so this should be fixed; if you still see it, file a bug.

"My anchors.txt file stopped doing anything"

anchors.txt is no longer read (replaced by filename tags in the 2026-06-09 rework). Stitchwork logs a one-time warning when it finds one. Anchors now live in the PNG file name as a trailing tag: @t top, @l left, @r right, @c center, and no tag (or @b) for the default bottom. Rename your sprite PNGs accordingly and delete anchors.txt. See Bigger Art: Anchors for the full migration steps.

Filing a useful bug report

A useful bug report includes:

1. Stitchwork version. Check the title bar of any Stitchwork window or the log line Stitchwork is loaded! Version: X.Y.Z.
2. What you did. Specific steps that lead to the bug. "It crashed when I opened the game" is less useful than "It happened after I loaded a save and walked into Greymoor."
3. What you expected vs what happened.
4. Other mods installed. List them — particularly anything that patches sprite, audio, or text loading. Many bugs are mod interactions.
5. The log file. Attach BepInEx/LogOutput.log if it's reasonable size (gzip if it's big). Without the log, we're guessing.
6. Screenshots or short clips. For visual bugs especially — "the text is garbled" is much clearer with a screenshot showing exactly what garbled looks like.

Without the log file, most bugs can't be diagnosed. The log captures exceptions, the order things loaded in, and what other mods were present. It's the single most useful artifact you can attach.

What's needed for this image: a redacted/sanitized example log excerpt showing what a healthy Stitchwork session looks like in the log, so users can sanity-check their own.

Known limitations

Accepted, documented limitations for the 1.0 line — known, with workarounds where they exist, not expected to block normal use. Fixes for several are planned for a later release.

• Minor UI bleed from same-name atlases. A few packs see small artifacts on certain icons or UI elements when two of the game's internal atlases share a "clean" name and Stitchwork can't tell them apart. Uncommon and cosmetic. A structural fix (per-atlas-instance matching) is planned post-1.0. Workaround: rename the colliding replacement away from the shared name, or scope your pack more narrowly.

• Colour grading can briefly drop under heavy pack loads. The reproducible cause was fixed; a residual remains where, with many packs active, scene colour grading may momentarily look absent on some scene entries. Re-entering the scene — or hitting Apply in the Pack Manager — restores it.

• The smoothness setting and "Verify integrity of game files." Stitchwork enables Unity's incremental garbage collector (via the game's boot.config) for steadier frame times. If you ever run Steam's Verify integrity of game files, that resets boot.config — Stitchwork detects it and re-applies the setting on the next launch (you'll see a restart notice). Nothing to do by hand.

• Keep only one copy of Stitchwork.dll. Stitchwork reads its workspace (your Text/, Sprites/, config) from the folder it actually loaded from. A leftover second copy anywhere under BepInEx/plugins/ — an old install you renamed, a backup, an unzipped release folder — is ignored for that resolution, but it trips BepInEx's duplicate-plugin guard and causes confusion (for example, edits that look like they won't revert because an old folder's files were being read). Delete stray copies; keep exactly one.

• Patchwork coexistence. If Patchwork.dll is present (a legacy install), Stitchwork stays inert by design — it and Patchwork conflict over sprite loading; remove Patchwork.dll. Architect-Silksong does not require Patchwork and coexists with Stitchwork fine.

• The Materials sub-tab (Dev Hub → Graphics → Materials) is research-grade tooling, not for end-user use, and is hidden unless DevMode is enabled.

For anything not listed here, check the current release notes or the community channel the latest release points to.