Repository navigation
Troubleshooting
First: update to the latest release. Many errors below are fixed, and an issue on an old release is asked to retry first.
Then open logs/mkw.log (or logs/setup.log if the setup failed; see
where it is), go to its last lines and search this page (Ctrl+F) for the
error you see there. Each section names the issue that tracks it: add your log there instead of opening a new one.
A crash ending in FATAL: vk: ... failed (-4) (the start screen says closed with code 70) is the GPU being lost.
The line that names the cause is usually further up than the FATAL line, so attach the whole log.
The setup reads the version from exefs/main. Only 1.0.0 and 1.8.0 are supported (1.8.0 from v0.1.9). The usual
cause is a dump with another update merged in. Dump 1.0.0 alone, or 1.0.0 with the 1.8.0 update. Tracked in
#18.
Your exefs and romfs are from different versions (typically 1.0.0's exefs/main with 1.8.0's romfs). Take
both from the same dump. From v0.1.12 the setup refuses the mix and says which version each part is.
#315
NVIDIA's shader tools arrived damaged, with a different checksum on each try: an antivirus scanning the download, a proxy or VPN, or a broken connection. Pause the antivirus or VPN and press Set up again (v0.1.10 retries 3 times). #207
The setup took PYTHONPATH or PYTHONHOME from another Python on your PC. Fixed in v0.1.10; on older releases,
remove those variables. #177
Fixed in v0.1.8 (the setup brings its own CA file). On older releases set
SSL_CERT_FILE=/etc/ssl/certs/ca-bundle.crt. #102
If you see one of these, you are on an old release: update.
| Log | Fixed in | Issue |
|---|---|---|
'gamelib.h' file not found |
v0.1.2 | #1 |
| stuck at 359/359 in Compile the game code | v0.1.4 | #2 |
spec.py, args.cc.split (a space in the folder's path) |
v0.1.5 | #29 |
max_workers must be <= 61 (more than 61 CPU threads) |
v0.1.10 | #222 |
nogame after moving the folder |
v0.1.10 | #188 |
commit physical memory … failed at the intro on 16 GB PCs |
v0.1.10 | #198 |
warm-up exits with 0xC0000409 on Windows |
v0.1.12 | #310 |
After updating by hand, the shaders of the old version stay until the setup runs again (prewarm: no pipeline keys
in the log). Open the start screen and press Set up. From v0.1.9 this happens by itself.
Listing the RomFS's ~205 000 files took minutes before v0.1.9. Update; an internal SSD is still faster.
The game closes in a race or a cup movie, sometimes with a driver reset. Two causes in our shader translator: the
first fixed in v0.1.11, the second (shaders that discard a pixel) fixed for v0.1.12. Update. To help, set
GPU_CRUMBS_DRAW = 1 in mkw.ini and add that run's log and your driver version to
#22.
The log stops with no error while a race builds its pipelines, and Windows' Event Viewer shows a crash in
nvgpucomp64.dll: NVIDIA's own shader compiler crashed. No fix yet. Set PIPE_TRACE = 1 and add the log to
#99.
The device is lost right after the same pair of programs (61fb5ce3… / d50d2bc0… in the log). Under
investigation, no workaround yet. #220
AMD's driver took minutes to compile a few shaders (black or broken screen, frozen splash). Fixed in v0.1.9. #111
Fixed in v0.1.8 (the mesh shaders run as compute passes on AMD's driver). If you set GPL = 0 for an old
workaround of #36, remove it. #88
Log: driver radv, task/mesh draws as mesh shaders, upload submit failed (-4). From v0.1.10 RADV draws the mesh
shaders as compute passes by default; on older releases set MESH_COMPUTE = 1. Later hangs (ROG Ally X) are still
followed in #50.
Log: device 0x1638, upload submit failed (-4). Not solved yet. Check the UMA frame buffer size in the BIOS and
add your log to #152.
Log: vendor 0x8086 and program ccfd8df6…. Fixed in v0.1.10.
#174
The GPU ran out of memory (integrated GPUs, cards with 2–4 GB). Set Texture quality to Half or Quarter
(TEX_QUALITY) and a lower Internal resolution. Remove any GPU_MEM_LIMIT, SPARSE_MIB or VRAM_MARGIN you set
by hand. #67
Fixed in v0.1.8. #83
Fixed in v0.1.9. #123
Fixed in v0.1.11 (photo mode at 1440 lines in v0.1.12). #255
no function at guest pc main+0x1bb0b34. Fixed for v0.1.12.
Discussion #193
Under investigation, no fix yet. It shows on dedicated GPUs that keep a copy of the game's memory in VRAM (the
mirror memory mode). Try MEMORY = import in mkw.ini (F1 → Advanced → GPU memory mode; it made the
artifacts go away in #279) and say in
#124 whether it changes anything, with that run's log.
Remove SPARSE_MIB, GPU_MEM_LIMIT or VRAM_MARGIN if you set them: too low leaves terrain without memory.
Fixed in v0.1.10 (docked) and v0.1.11 (handheld). #195
The first time an effect or course is drawn, its pipeline is compiled. Each new one is saved in pipeline-keys.bin
and built in the background at the next start, so a hitch should happen once. If it repeats after a restart, report
it with that second run's log.
The game's logic is tied to its frames, as on the console: if your GPU cannot hold 60 fps the race slows down. Lower Internal resolution, or set FPS to 30 (with Frame generation 2 for smoothness).
Texture quality: Half (TEX_QUALITY = half) and 720 lines. Part of the game's memory is read over PCIe on these
cards; a real fix is planned.
That is FSR's sharpening: set Sharpness to 0 or the upscaler to bilinear. The internal resolution applies after a restart.
That is the game's own SDR grading. With an HDR display, turn HDR on in the OS: HDR on auto shows the game's HDR picture.
Allow userfaultfd in the container's seccomp profile.
A crash or glitch with mods on is reported to the mod's author first. Check that each mod is enabled once, that it
was added with Import on the Mods page (folders copied by hand into mods/ are not loaded: the log says
RomFS overlay: none), and that it is made for your game version (1.0.0 or 1.8.0). Try with mods off before
opening an issue.
RecompLauncher (a third-party launcher) posts only the end of the log. Attach the whole file, which it keeps in
%APPDATA%\com.recomplauncher.app\game-output\mkw-recomp.log.
Something wrong or missing here? Say so in Discussions. mkw-recomp is not affiliated with Nintendo.