MKW Recomp

Troubleshooting & fixes

Solutions verified against adriadam10/mkw-recomp issues and release notes through v0.1.8, plus mkw.ini overrides and crash log locations.

Download v0.1.8Setup guide
  • Logs (Win): ./logs/
  • Logs (Linux): ~/.local/share/mkw-recomp/logs/
  • Latest fix build: v0.1.8
Macro view of the Valve Steam Deck mainboard PCB and RDNA2 APU assembly
Handheld RDNA2 mainboard assembly

Known symptoms & verified upstream fixes

Every solution below maps to specific issues and commits in adriadam10/mkw-recomp through v0.1.8:

Symptom / ErrorFix or Workaround
Black race 3D or diagonal cut menus on Intel (ANV / Arc), Adreno or AMD Windows 26.10Fixed in v0.1.8 (#26, #64, #105): full-screen passes left position.w undefined and integer colour targets needed integer reads/writes. Update to v0.1.8; Prepare automatically re-runs the shader stage.
Window never opens after Play or freezes on title (AMD Windows)Fixed across v0.1.7 & v0.1.8 (#36, #38, #54, #88): switch-heavy shaders no longer stall AMD’s compiler for minutes, and race mesh draws run as compute passes on AMD Windows. Remove any old GPL=0 workaround from mkw.ini.
Races run in slow motion below 60 fpsOpen Settings > Screen > Frame rate and select 30 instead of Automatic. Check game: speed in logs/mkw.log; lower internal resolution to 720p if frame time still exceeds 33.3 ms.
Game stops after a while in Free RoamFixed in v0.1.8 (#63): when the game initialized online sockets, execution halted. Sockets now reply immediately as an offline console.
Flat course ground, missing textures or black terrain on high/low VRAM GPUsFixed in v0.1.6 & v0.1.8 (#31, #43, #63, #68): dedicated GPUs now get 25% of VRAM (768 MiB–3 GiB) for tiled textures, starting at 8 blocks, with system-RAM fallback. You can manually set SPARSE_MIB=1024 or GPU_MEM_LIMIT in mkw.ini.
Setup stuck at “Compile the game code” 359/359 or 359/360 on WindowsFixed in v0.1.3 & v0.1.4 (#2, #12): bundled zig 0.17.1 now ships prebuilt C runtime objects so it never hangs building CRT on first link, and Windows Defender exclusions on your folder speed linking up further.
Shader step fails with BrokenProcessPool or FileNotFoundErrorFixed in v0.1.4 & v0.1.5 (#24, #29): spaces in folder paths now work, and if RAM runs out the worker pool automatically scales down by half down to 1 worker. Close heavy browsers during Prepare on 8–16 GB RAM PCs.
Crash pressing HOME or Alt-Tabbing during startup logoFixed in v0.1.8 (#83, #89, #92). Update via the start screen or unpack {TAG}.
TLS certificate error downloading nvdisasm on NixOS / minimal LinuxFixed in v0.1.8 (#102) by probing non-standard CA bundle paths during Prepare.

Useful mkw.ini keys & diagnostics

mkw.ini sits next to mkw.exe on Windows and inside ~/.local/share/mkw-recomp/ on Linux:

  • Remove GPL=0: older community threads suggested adding GPL=0 on AMD Windows (#54); since v0.1.7 upstream explicitly advises removing it.
  • SPARSE_MIB: manually overrides the tiled course texture budget in MiB (default is 768 on iGPUs, or 25% of VRAM up to 3,072 MiB on discrete GPUs).
  • GPU_MEM_LIMIT: caps dedicated video memory usage alone (fixed in v0.1.6, #28).
  • GPU_CRUMBS_DRAW=1: records per-draw shader breadcrumbs into logs/mkw.log to pinpoint driver device-loss faults (#37, #40).

How to file a useful upstream bug report

Before opening an issue at github.com/adriadam10/mkw-recomp/issues, reproduce on v0.1.8 and attach:

  1. logs/mkw.log (runtime, Vulkan device fault addresses via VK_EXT_device_fault, and VK_AMD_buffer_marker / present breadcrumbs).
  2. logs/setup.log if the failure happened during Prepare.
  3. Your exact GPU model, driver version, OS, and internal resolution. Never attach copyrighted game files or dumps.
Go-karts banking through a hairpin bend past starting grid markings at Mika Salo Circuit
Mika Salo Circuit karting hairpin and grid
A racing kart streaking past red and white circuit kerbs at speed
Sprint kart passing painted apex kerbs
Two go-karts rounding an outdoor asphalt corner at Snetterton Circuit
Outdoor karting corner at Snetterton Circuit

Common questions

Why does mkw-recomp say my game version is unsupported?

Only decrypted Mario Kart World version 1.0.0 (with both exefs/ and romfs/) is supported right now. Updated dumps like 1.8.0 have different binary layouts (#19).

Do I need to re-run Prepare from scratch when updating?

When updating from v0.1.7 to v0.1.8, only the changed stages (such as the updated shader translator) re-run automatically, and v0.1.8 caches compiled C objects in setup-work/obj for future updates.