TROUBLESHOOTING FIXES
Diagnose and resolve common Project ReLink build, startup, and Vulkan 1.3 runtime issues using relink_log.txt, relink_exefs_mods.txt, and verified relink_env.txt diagnostic flags.

Known Project ReLink Errors & Verified Solutions
Matched directly against active reports and fixes in the pixl27/ProjectReLink issue tracker.
| Symptom / Error Message | Root Cause | Verified Fix |
|---|---|---|
| Long pause on first launch (~16 minutes) | One-time shader translation and driver/compute pipeline cache build (repeats after GPU driver updates) | Wait for the progress screen to complete; on AMD GPUs update to v0.7.9 (#85/#93 fixed AMD startup hangs & FIFO throttling during shader prep). |
| Vulkan loses connection / Device Lost (RTX 5070 #90, Radeon 890M #94) | Driver timeout during heavy ASTC texture decode or uncapped GPU boost spikes | Update GPU drivers, update Project ReLink to v0.7.9+, test 75% 3D scale or 30, smooth cap, and disable GPU undervolts/overlays. |
| Insert menu will not open (#96 / #98) | Compact keyboard missing physical Insert key or sub-720p window bounds | Update to v0.7.9+, run at 1280x720 or higher, and press Fn + Insert (or use Windows On-Screen Keyboard osk.exe to test). |
| Black cliffs in Hyrule Field or blurry rocks | Damaged RBake_Scene or actor mip packs in user dump |
Update to v0.7.9 and rebuild so tools/dump_repair.py populates mods\00-dump-repair automatically. |
| "Exefs mods changed since the last build" | Added, edited, or deleted .ips / .pchtxt patch in mods\<name>\exefs\ |
Click Build again on the launcher's first page and inspect relink_exefs_mods.txt for conflicts. |
| High RAM usage or leftover 800 MB cache (#92) | Legacy mkw_vk_pipelines.bin from pre-v0.7.6 builds or drawn-texture retention |
Upgrade to v0.7.8+ (auto-deletes obsolete mkw_vk_pipelines.bin and keeps lean startup pipelines active). |
| Black squares on Link's shadow near water (#84) | Known shadow-map precision edge case near water planes tracked upstream | Test native 100% 3D resolution without third-party shadowpchtxt mods and follow upstream issue #84 for renderer commits. |
Diagnostic Environment Flags in relink_env.txt
Isolate whether a graphical glitch comes from occlusion queries, async threads, or ReShade hooks.
# Diagnostic fallback flags (place in Games\ReLink\relink_env.txt one at a time)
RX_VK_OCC_QUERIES=0
RX_VK_REAP=0
RX_VK_ASYNC_LOAD=0
RELINK_LOW_PRIORITY=1
RELINK_JOBS=4
When filing a bug report at pixl27/ProjectReLink/issues, always attach relink_log.txt from your game folder together with your CPU, GPU model, driver version, and whether any folders exist inside mods\.
Recommended PC Hardware
Verified storage and controller upgrades matched to AVX2 static compilation, 60 GB build scratch space, and dynamic HUD button prompts.
Hardware note: As an Amazon Associate we earn from qualifying purchases at no extra cost to you. Project ReLink requires an AVX2 CPU, 16 GB RAM, ~60 GB free NVMe SSD space during compilation, and an XInput/SDL controller.
Samsung 990 PRO 2TB PCIe 4.0 NVMe SSD
Sustains high random I/O across the 60 GB C compilation workspace and 16-minute first-boot Vulkan pipeline generation.
WD_BLACK SN850X 2TB NVMe Internal SSD
Dedicated secondary game drive for fast ASTC texture streaming and async background shader cache reads in Hyrule Market.
Xbox Wireless Controller (Carbon Black)
Native XInput support with automatic Xbox HUD glyph replacement (prompts\keytex.bin) and radial Item Wheel stick targeting.
8BitDo Ultimate 2C Wireless Controller
Drift-resistant Hall Effect sticks ideal for Project ReLink circular stick deadzone tuning (0 to 50%) and quick R/L item cycling.
Project ReLink FAQ
Direct engineering answers verified against the GPL-3.0 pixl27/ProjectReLink repository and release artifacts.
Where is relink_log.txt located?
Inside your compiled game directory (by default Games\ReLink\relink_log.txt next to relink-game.exe). It logs your GPU driver, active relink_env.txt flags, every loaded RomFS mod, and Vulkan error codes.
My PC freezes during the 10-45 minute C compilation step. How can I throttle CPU load?
Set RELINK_LOW_PRIORITY=1 and RELINK_JOBS=4 (adjust to half your CPU threads) before running make_game.py or rebuilding so background clang processes leave headroom for Windows.