Dusk / Dusklight Known Issues & Workarounds
Real GitHub-tracked Dusk bugs — what v1.0.1 fixed (Apple Silicon, Windows non-English usernames, Ilia hair, iOS saves) and what's still open.
This is a verified issues list — every entry below is sourced to a real GitHub issue, official FAQ entry, or multi-user community report. We don’t list “common errors” we haven’t actually seen reported.
If your specific problem isn’t here, check the Dusklight GitHub issues page for the latest reports, or ask in the team’s Discord at discord.gg/dusktp (run by them — not us).
Last updated: 2026-06-20. Most issue statuses below reflect ground truth as of the v1.0.1 release on 2026-05-11; see the v1.4.0 and v1.4.1 notes for additional crash, regression, and mobile fixes shipped on 2026-06-16.
Jump to a specific issue
Each issue below also has its own focused page with a self-contained fix. Searchable by error message:
Crashes & launch failures
- Apple Silicon shader-cache crash (#826) — open at v1.0.1
- macOS “Dusklight is damaged and can’t be opened” — Gatekeeper fix
- Linux AppImage “Couldn’t create directory /TwilitRealm” (#818)
- Windows cutscene / Faron lake crash (#819)
Disc / ROM
Controller & input
Graphics
Performance
Save migration
The full categorized list (with workarounds and source citations) continues below.
✅ Fixed by v1.0.1 (2026-05-11)
If you were on v1.0.0 and hit one of these, update to v1.0.1.
| Issue | Symptom | v1.0.1 fix |
|---|---|---|
| #779, #805 | Apple Silicon launch crash | Closed by collaborator tomlube: “Fixed in 1.0.1” |
| #807 | Windows non-English username silent launch failure | Unicode filepath handling added |
| #804 | iOS save not user-accessible | Dusklight data now appears in Files app on Android + iOS; new “Open Data Folder” menu under Settings → Interface |
| #821 | Recording Mode kills music until restart | Fixed |
| #827 | Android Ilia missing hair (Adreno alpha-discard) | Workaround shipped |
| #830 | macOS keyboard binding broken | Fixed |
| Default controller mappings (Z/Back) | Wrong-by-default mapping | Defaults corrected |
| Gyro sensitivity axis names swapped | Pitch/yaw labels mismatched | Labels fixed |
| Window minimize freeze | Some configs froze on minimize | Fixed |
| Monitor-scaling crash | Crash moving between monitors with different DPI | Fixed |
For the full v1.0.1 patch notes, see the changelog.
✅ Also fixed by v1.4.0 (2026-06-16)
v1.4.0 fixed several crashes and bugs that aren’t individually tracked on this page but are worth noting if you hit them:
- Crash when talking to the Zora under the waterfall in Zora’s Domain
- Hidden Village crash after getting Ilia’s Charm from Impaz
- Monkey loading crash in the Forest Temple
- Respawning in the final Zant fight phase
- Ganondorf’s cape texture & tearing
- Performance issues & crashes with map rendering
- macOS 12 support restored
See the changelog for the full v1.4.0 notes.
✅ Also fixed by v1.4.1 (2026-06-16)
v1.4.1 is a same-day hotfix on top of v1.4.0. If v1.4.0 introduced new problems for you, update to v1.4.1 — it addresses:
- Texture replacement regressions from v1.4.0 (load ordering & missing UI textures)
- Performance regression on some GPUs (AMD on Windows in particular)
- Keyboard focus issues on Android and iOS
- 4:3 aspect lock issue on PowerVR GPUs
- Hidden Dusklight menu still receiving inputs in some circumstances
- GPU backend fallback regression
See the changelog for the full v1.4.1 notes.
Crashes & Launch Failures
Apple Silicon shader-cache crash (separate from #779/#805)
Issue: #826
Symptom: Crash on launch on M-series Macs with a WebGPU/Metal RmlUi Gradient Pipeline shader-compile failure. This is a different bug from the original “Dusk quit unexpectedly” dyld symbol-missing crash documented at v1.0.0 — that one was #779 / #805 and is closed in v1.0.1.
Status (2026-05-13): Open, under investigation. Labeled “Known shader cache crash on macOS currently.”
Workarounds:
- Try a different Graphics Backend in Settings → Prelaunch → Graphics Backend — cycle Metal / Vulkan / OpenGL
- Watch #826 for fix updates
Windows non-English username — FIXED in v1.0.1
Issue: #807 — closed
Was: Dusklight didn’t launch when Windows username contained non-Latin characters (e.g., C:\Users\ミドナ).
Fix: Unicode filepath handling shipped in v1.0.1 (2026-05-11). Update to v1.0.1 if you hit this.
Linux AppImage: “Couldn’t create directory ‘/TwilitRealm’”
Issue: #818 Symptom: On Linux (CachyOS reported), an AppImage variant fails to launch with:
[fatal] [dusk] Unable to get PrefPath: Couldn't create directory '/TwilitRealm': 'Permission denied'Status: Open. Affects an AppImage variant; the official .zip builds are unaffected.
Workarounds:
- Use
Dusk-v1.0.0-linux-x86_64.zip(orlinux-arm64.zip) instead of any AppImage - If you’ve run the AppImage already, clean up:
sudo rm -rf /TwilitRealm
Mac: “Dusklight is damaged and can’t be opened”
Cause: Gatekeeper quarantine attribute. Dusklight is not notarized. Status: Expected behavior on first launch (not a bug per se). Fix: In Terminal:
xattr -cr /Applications/Dusklight.appThen launch normally. Or right-click → Open the first time.
Random crashes mid-cutscene / mid-gameplay (Windows)
Issue: #819 Reporter setup: Windows 11, i9-13980HX, RTX 4060, Xbox One controller. Symptom: Crashes during specific cutscenes (Zelda dialog, Ordona dialog) and during Faron Woods poison lake platforming. Reporter had Fast Spinner, Fast Iron Boots, and fullscreen enabled. Status: Open. Workarounds:
- Disable cheat-style options (Fast Spinner, Fast Iron Boots) before key cutscenes
- Try windowed mode instead of fullscreen
- Watch the linked issue for updates
Disc / ROM Issues
”The selected disc image did not pass hash verification”
Cause: Your dump’s XXH128 doesn’t match Dusklight’s expected hash. Most often: corrupted dump, wrong region, or a modified/scene release. Fix:
- Verify the SHA-1 of your dump:
- Windows:
Get-FileHash -Algorithm SHA1 yourdump.iso - macOS / Linux:
shasum -a 1 yourdump.iso
- Windows:
- Should match exactly:
75edd3ddff41f125d1b4ce1a40378f1b565519e7(NTSC-U)2601822a488eeb86fb89db16ca8f29c2c953e1ca(PAL)
- If neither matches, re-dump using the legal dump guide with checksum verification ON.
”The selected game is not supported by Dusklight”
Cause: You loaded a GameCube Japan, Wii, Wii Korea, or Wii U HD disc image. v1.0.0 only accepts GameCube NA and PAL. Fix: Use a GameCube NA (GZ2E01) or PAL (GZ2P01) disc dump. Other regions are on the project’s roadmap (per README).
Modded ISO won’t load
Behavior: Hash mismatch is expected when you modify the ISO (e.g., applying the Linkle character mod). Dusklight shows a warning but offers a “Continue anyway” path:
“Just install the [mod] as you usually would directly to the GameCube or Wii .iso and then direct Dusklight to that modded .iso file and confirm that you still want to use it when it tells you it’s probably corrupted or modified.” — TomoAries, r/pcgaming, 14 upvotes
So mods work — Dusklight just warns you that the hash differs from the known-good values.
Controller & Input Issues
Selecting non-GCN controller with WUP-028 adapter creates 4 GiB junk file
Issue: #810
Symptom: With Nintendo’s WUP-028 GameCube USB adapter connected, selecting a non-GCN controller from the dropdown writes a junk file of 2^32 + 32 bytes (~4 GiB), mostly zeros. Causes long hangs on HDDs and brief hangs on SSDs.
Status: Open.
Workarounds:
- Disconnect the WUP-028 adapter before changing controller selection
- Or pick the matching GCN controller in the dropdown
Cannot bind keyboard on macOS — FIXED in v1.0.1
Issue: #830 — closed Was: Keyboard binding through Dusklight’s controller config UI didn’t work on macOS. Fix: Keyboard binds repaired in v1.0.1 (2026-05-11). Update to v1.0.1 if you hit this.
Steam Controller leaves mouse cursor on screen
Issue: #811 Symptom: When using a Steam Controller, the mouse cursor remains visible during gameplay. Status: Open.
AYN Thor rumble doesn’t work
Issue: #812 Status: Open. AYN Thor handheld supported; rumble specifically broken.
Cannot rebind interface (menu) controls
Issue: #824 Symptom: You can rebind game controls but not the menu / UI navigation controls. Status: Open enhancement request.
No D-Pad menu navigation
Issue: #814 Symptom: D-Pad doesn’t navigate menus. Status: Open enhancement request.
Right shoulder / Z mapping confusion
Community report: r/pcgaming user LargeBirdInATree:
“Right Bumper is mapped to Right Trigger under ‘Digital Trigger’. I don’t know what ‘Digital Trigger’ is, and pressing left and right shoulder doesn’t appear to do anything.”
Workaround: In Settings → Input → Controller → Configure Controller → Triggers, the “Digital Trigger” terminology refers to whether the triggers report as analog or digital. Cycle through configurations until the bumpers + triggers match what your physical controller expects.
Graphics / Display Issues
Pulsating bloom at unlocked framerate
Issue: #825 (label: Interpolation) Symptom: Bloom effect pulses noticeably when Settings → Video → Rendering → Unlock Framerate is enabled. Status: Open. Workaround: Lock framerate (toggle Unlock Framerate off) until patched.
21:9 cutscenes cropped vertically
Issue: #813 Symptom: On ultrawide (21:9) displays, in-game cutscenes are cropped at top and bottom. Status: Open. Workaround: Use 16:9 for cutscenes, or lock 4:3 aspect ratio (Settings → Video → Display → Lock 4:3 Aspect Ratio) — the latter ensures consistent framing throughout.
Bo’s house table shadows cropped
Issue: #815 Symptom: Specific lighting bug at Bo’s house in Ordon Village. Status: Open.
Mini-map moves when mirror mode enabled
Issue: #809 Symptom: Cosmetic positioning bug for mini-map in Mirror Mode. Status: Open.
First-person switch hiccups
Issue: #816 Symptom: Brief hitch when switching to first-person view. Status: Open.
Internal resolution looks like 4:3 even with 4:3 lock off
Community report (r/SteamDeck): User SEANPLEASEDISABLEPVP (3 upvotes):
“the ‘internal resolution’ setting for me defaults to 1216×896 for some reason, it looks like a 4:3 aspect ratio even though that’s turned off. EDIT: Nevermind, I had to toggle fullscreen lol.” Workaround (verified): Toggle fullscreen on/off in Settings → Video → Display → Toggle Fullscreen.
Audio Issues
Recording Mode kills music until restart — FIXED in v1.0.1
Issues: #821, #832 — closed Was: Toggling Settings → Interface → Recording Mode off didn’t re-enable music; required a Dusklight restart. Fix: v1.0.1 (2026-05-11). Music re-enables correctly when Recording Mode is toggled off.
Mobile Issues (Android & iOS)
Android: Ilia missing hair — FIXED in v1.0.1
Issue: #827 — workaround shipped Was: On various Android devices (Retroid Pocket 5, Samsung Galaxy series, others), the character model for Ilia rendered without hair. Confirmed by multiple Reddit users (splashtext 43 upvotes, Shizzawn, OutsiderInCider). Fix: v1.0.1 (2026-05-11) ships an Adreno GPU driver workaround for alpha discard. Update to v1.0.1.
Android: Galaxy S26 Ultra visual bug (“string cheese”)
Issue: #801 Status: Open. Adreno 840 (Snapdragon 8 Elite Gen 5) appears to have multiple residual issues — stretched textures, vertex explosions, LOD bugs. Tracked alongside #750, #846, #1184. Per the official README: “we are also aware of a number of issues on devices with Adreno GPUs and are working to resolve them.”
iOS: Save location not user-accessible — FIXED in v1.0.1
Issue: #804 — closed Was: Save file lived in iOS app sandbox; not visible in Files app for backup or transfer. Fix: v1.0.1 (2026-05-11) makes Dusklight data visible in the Files app on both iOS and Android. Also adds a new Settings → Interface → Open Data Folder menu that jumps directly to the location.
Android save sandbox path
The Android package identifier is dev.twilitrealm.dusk (not com.twilitrealm.dusk). Saves live under /sdcard/Android/data/dev.twilitrealm.dusk/files/ with structure including Texture_Replacement/. From v1.0.1 onward, use the in-app Open Data Folder button rather than navigating manually.
Save Migration Issues
Dolphin save not appearing in Dusklight
Cause: Wrong filename, wrong path, or wrong save format. Fix (per official FAQ):
- The Dolphin save file is at:
- Windows:
Documents\Dolphin Emulator\GC\USA\Card A\01-GZ2E01-gczelda2.gci - macOS:
~/Library/Application Support/Dolphin/GC/USA/Card A/01-GZ2E01-gczelda2.gci - Linux:
~/.local/share/dolphin-emu/GC/USA/Card A/01-GZ2E01-gczelda2.gci
- Windows:
- The Dusklight save folder is at:
- Windows:
%APPDATA%\TwilitRealm\Dusklight\USA\Card A\ - macOS:
~/Library/Application Support/TwilitRealm/Dusklight/USA/Card A/ - Linux:
~/.local/share/TwilitRealm/Dusklight/USA/Card A/
- Windows:
- Replace
USAwithEURif you’re using the PAL disc
If your Dolphin save is in .raw format (single memory card image instead of separate .gcis), use Dolphin’s Memory Card Tool to extract the individual .gci first. Or change Dusklight’s Settings → Prelaunch → Save File Type to Card Image to use .raw directly.
Save loaded but progress doesn’t carry over
You may have loaded an empty save slot. In TP, load from Card A (which is what 01-GZ2*-gczelda2.gci represents). The other slots are typically empty.
Performance Issues
Stuck at 30 FPS even with Unlock Framerate enabled
Community report (r/pcgaming): User Thr0waway_Joe:
“I can’t get it past 30fps. Even with unlocked fps” Status: Sporadic, no definitive root cause as of v1.0.0. Possible causes:
- VSync still capping (Settings → Video → Display → Enable VSync → toggle off)
- Monitor refresh rate cap
- Graphics backend bottleneck — try a different one (Settings → Prelaunch → Graphics Backend)
Performance lower than expected
- Lower Internal Resolution (Settings → Video → Resolution)
- Cap framerate to 60 instead of unlocked
- Disable post-processing (Settings → Video → Post-Processing → Bloom)
- Try a different Graphics Backend (D3D12 / Vulkan are usually fastest on PC; Metal on Mac; OpenGL ES on mobile)
“Disputed” / “Resolved” Reports
”Mirror Link battle unwinnable at uncapped FPS” (DISPUTED)
A user (r/pcgaming, WiglyWorm, 10 upvotes) claimed:
“I just watched a video where someone was playing this game uncapped and certain things like the mirror link battle were actually unwinnable due to FPS changes.”
Counter-clarification by liamwilliams93:
“on this recomp it still runs the game logic at 30fps and uses interpolation to render at higher frame rates”
Verdict: Dusklight’s design decouples logic (30 Hz) from rendering. The “FPS-tied gameplay break” is not how Dusklight works. The original user may have been thinking of a Dolphin or earlier port-attempt patching scheme. Dusklight’s interpolation does not affect game logic timing.
Bugs Already Fixed (Don’t Re-Report)
These were fixed in v0.x.x → v1.0.0 — if you’re on v1.0.0, they don’t apply:
- Windows Unicode paths in appdata folder (#767, #755 — closed)
- Gyro sensitivity axes swapped (#764, #759 — closed)
- Linux x86_64 didn’t start after configuring settings (#788 — closed)
- GameCube controller B / X swap default (#732 — closed)
- Recording Mode mute streams initial bug (different from #821) (#735 — closed)
- Mac: Fails to open after clicking livesplit setting (#773 — closed)
If you’re hitting one of these, you may be on an older version. Update to v1.0.0.
How to Report a New Bug
If your problem isn’t on this list:
- Check the Dusklight GitHub Issues page (someone may have reported it)
- If new, file a new issue on GitHub with:
- OS + version
- Dusklight version
- Steps to reproduce
- Screenshots if visual
- Or post in the Dusklight team’s Discord at discord.gg/dusktp
We don’t accept bug reports for Dusklight — we’re an independent content site, not the project. Reports go directly to TwilitRealm.
Version History on This Page
| Date | Change |
|---|---|
| 2026-05-10 | Initial publication based on v1.0.0 GitHub issues snapshot + community reports from launch day |
| 2026-06-16 | Added v1.4.0 crash-fix note (Zora waterfall, Hidden Village, Forest Temple monkey, final Zant phase, map rendering, macOS 12) |
| 2026-06-20 | Added v1.4.1 hotfix note (texture replacement regressions, AMD-on-Windows performance, Android/iOS keyboard focus, PowerVR 4:3 lock, hidden-menu input leak, GPU backend fallback) |
This page reflects state at v1.0.0 as of 2026-05-10. Dusklight releases patches frequently — bookmark and check back, or watch the GitHub releases page for the latest.