Troubleshooting & flags

Verified workarounds, runtime environment variables, and diagnostic flags for Lucas-blip-png/dkb-pc-recomp (v0.3.0).

Log file: dkb.log
Lazy RAM: TOTK_HEAP_LAZY=1
Dyn UBO: TOTK_DYN_UBO=1
Pass threads: DKB_REPLAY_THREADS

GPU silicon pipeline (Ampere to Maxwell to SPIR-V)

Known symptoms & verified upstream fixes (v0.3.0)

Every issue and workaround below is sourced directly from Lucas-blip-png/dkb-pc-recomp release notes and open/closed issue reports:

Symptom / Error	Upstream Fix or Workaround
High RAM commit (~14.5 GiB) or out-of-memory crash on 16 GB PCs	Set `TOTK_HEAP_LAZY=1` on Windows (added in v0.3.0, #126) to commit guest heap memory on first touch, reducing first-level commit to ~9.3 GiB. Also ensure your Windows virtual memory commit limit is at least 24 GiB.
Installer refuses folder path or fails immediately (#189)	In v0.3.0, work folder paths containing shell-special characters (parentheses, quotes, ampersands) are refused before compilation starts. Extract and build inside a plain path like `C:\Games\DKB` or `~/Games/DKB`.
Linux setup.sh fails at dkb_shaders with ModuleNotFoundError: compression / zstandard (#200)	Install `zstandard` into the installer’s virtual environment (`uv pip install --python .venv/bin/python zstandard`) and ensure the shader translator binary has execute permissions (`chmod +x`).
Device lost / vkQueueSubmit2 (-4) on AMD Radeon GPUs (#3, #84, #99, #122, #193, #198, #204)	AMD support is experimental. In v0.3.0, test the two upstream AMD device-lost aids: `TOTK_FIX_VS_FAULT=all` and `TOTK_CRUMB_BIND=1`, and attach `dkb.log` to Issue #3 or #204. (Cyan map wedges #125 and bloom NaN bands #132 were fixed in v0.2.0.)
Low FPS in dense areas (Hilltop Layer, sublayer 200, open areas)	In v0.3.0, test `TOTK_DYN_UBO=1` (+16% fps in dense areas via dynamic fragment uniform buffers, #161), `DKB_REPLAY_THREADS=6` (slices large passes across worker threads, #195/#211), or `TOTK_REPLAY_PAR=1` (#164).Note: if using DLSS on v0.3.0, parallel pass slicing is skipped until PR #209 lands.
Frame limit below 60 fps does not hold on base 1.0.0 (#118)	Turn on "Game speed follows the clock" in Display settings. Without it, base 1.0.0 keeps its internal timing when capped below 60 fps.
Donkey Kong cannot climb walls or grates (#201)	Happens when the active frame rate exceeds 60 fps (#201). Set the FPS limit to 60 (you can still use `FRAME_GEN=2x` for display smoothness).
Radial blur stays stuck on screen after a smash above 60 fps (#158)	Fixed in v0.3.0 (#159) on update 3.2.0 under the experimental dynamic step.
1080p looks overly pixelated after updating (#210)	In v0.3.0, DLSS output uses the game’s native 3D resolution and `render_scale` has no effect on Bananza. Check the Display and Graphics tabs (#170) to confirm your output resolution and upscaler preset.
Device lost in Glacier layer rock ride (#196) or after first guide movie on NVIDIA (#9, #75)	The #9 light-quad skip and #75 end-of-tutorial cutscene workarounds are enabled by default on NVIDIA. The Glacier rock ride fault on RTX 5090 Laptop is tracked in Issue #196.

Environment variables & diagnostic switches

DKB Recomp exposes runtime environment variables (shared with its TotK Recomp host and Bananza-specific extensions) for memory tuning, multi-threaded replay, HDR and crash triage:

Environment Variable	Subsystem	Effect in DKB Recomp
`TOTK_HEAP_LAZY=1`	Windows memory	Commits guest heap on first touch; drops first-level commit from ~14.5 GiB to ~9.3 GiB (#126).
`TOTK_DYN_UBO=1`	Vulkan descriptors	Uses dynamic uniform buffers in the fragment set (+16% fps in dense areas, #161).
`DKB_REPLAY_THREADS=N`	Multi-threaded replay	Slices large passes across N worker threads, each with its own draw context (#195; try 6 on an 8-core CPU, #211).
`TOTK_REPLAY_PAR=1`	Helper threads	Translates long runs of draws on helper threads (3 helpers on 8+ logical CPUs, 2 on 4 CPUs, #164, #185).
`DKB_HDR_NATIVE=1`	HDR10 (3.2.0)	Uses Bananza’s native HDR10 output when `hdr = 1` and scales highlights to display peak (#150).
`FRAME_GEN=2x`	Frame generation	Inserts an interpolated frame half an interval before each real frame in mailbox/immediate mode.
`TOTK_FPS_LIMIT=unlimited`	Frame pacing	Uncaps the frame rate limit (#113; note climbing bug above 60 fps in #201).
`TOTK_FIX_VS_FAULT=all`	AMD diagnostics	Vertex-stage fault aid for investigating AMD device-lost crashes in v0.3.0.
`TOTK_CRUMB_BIND=1`	GPU breadcrumbs	Records bind breadcrumbs to narrow down driver device-loss faults.
`TOTK_SVC_SLOW=1`	OS diagnostics	Logs guest Horizon service calls that block for 100 ms or longer (#182).
`TOTK_MEM_REPORT=N`	Memory profiler	Logs where process memory commitment is allocated.
`DKB_DRAW_PROFILE=1`	Replay profiler	Breaks down command-buffer replay time by section in the performance log (#153, #211).

How to report a bug upstream

When filing an issue at github.com/Lucas-blip-png/dkb-pc-recomp/issues, always include:

Your dkb.log file (including the top build line dkb 0.3.0+<commit>).
Your exact GPU model, driver version, operating system, and whether your dump is 1.0.0 or 3.2.0.
What you were doing immediately before the crash. Never attach generated C files, keys, ROMs, shader caches or screenshots showing copyrighted game content (enforced by python tools/check_content.py --staged).

Controllers for DKB Recomp

DKB Recomp recommends a gamepad on Windows, Linux and macOS via its SDL3 Horizon host, with dedicated Controller and Mouse & Keyboard settings tabs plus Bananza action descriptions. These controllers pair cleanly on PC:

Controller	Best For in DKB Recomp	Hardware Advantage	Link
GameSir Cyclone 2	Tunnel punching & 3D camera control	TMR sticks, Hall linear/microswitch triggers, 1000 Hz wireless dongle	View on Amazon
8BitDo Ultimate 2 Wireless	Desktop Windows & Linux setup	Zero-drift TMR sticks, charging dock, Switch/XInput mode switch	View on Amazon
Sony DualSense	Low-latency USB & SDL3 prompts	Responsive face buttons, crisp D-pad, native SDL3 HID support	View on Amazon
Xbox Wireless Controller	Plug-and-play Windows 10/11	Native Windows XInput & Linux xpadneo pairing with zero setup	View on Amazon

As an Amazon Associate, this site earns from qualifying purchases.

Stepped limestone tiers of the Temple of the Inscriptions surrounded by dense jungle canopy at Palenque — Stepped stone tiers and jungle canopy at Palenque

Desktop gaming PC workstation with dual monitors and tempered glass chassis — Windows x64 desktop workstation for Vulkan 1.3 and DLSS

macOS ARM64 preview target (MoltenVK and GfxBackend)

Common questions

Why are some particles missing on NVIDIA GPUs?

To prevent the GPU fault after the first guide movie (Issue #9, seen across NVIDIA drivers 617.14, 617.42 and 621.01), DKB Recomp skips two light quads by default, which hides certain particle effects (Issue #62).

Why does the validation layer log 10 errors on R32_SFLOAT?

Upstream notes that the Vulkan validation layer reports 10 errors from a depth-compare sampler bound to an R32_SFLOAT view; no visible rendering defect has been linked to it.