Troubleshooting & fixes
Verified solutions for setup errors, exit code 4, Vulkan device loss, shader translation stops, and Link Play connection issues.
- Logs: pkp.log & setup.log
- Relay IP: 204.216.111.91:47610
- Crash logs: pkp_crash.txt
- Stable fix: v0.11.1
Common error messages & verified fixes
Every symptom and fix below is sourced directly from the Dittobyte/Recompia README, issue tracker, and release notes through v0.11.1 and v0.12.0-beta.1:
| Error / Symptom | Root Cause & Verified Fix |
|---|---|
| "pkp.exe exited with code 4" or launcher says romfs is incomplete | Your dumping tool wrote the 2.0.1a update’s romfs without the base game’s files underneath it. Keep base/ next to updates/ (each with exefs/ and romfs/) inside one parent folder, pick that parent folder in PokopiaLauncher, and press Set up again so the launcher merges the missing base files automatically. |
| "pkp.exe exited with code -1073740791 (0xC0000409)" at start on AMD GPUs | Fixed in v0.10.3 (#487): a compute shader requested a 32-wide subgroup on an AMD workgroup too large for it. Update to {TAG} or newer so oversized compute workgroups run at the driver’s native width. |
| "The graphics device was lost" on Steam Deck / Linux or full freeze on Linux NVIDIA | Fixed in v0.11.0 (#531, #533): stale host-visible graphics memory next to an active GPU write caused compute light-list shaders to loop indefinitely. Update to {TAG}; the runtime now synchronizes that memory and enforces [nvn] loop_guard. |
| "Translating shaders: 0 of 99012" (translator closes silently during Set up under Proton) | Fixed in v0.11.0 (#530): when a shader batch runs out of memory under Proton, Set up automatically retries the batch with lighter settings (workstation GC and 2 worker jobs) and keeps them for the rest of the run. |
Set up fails at "Linking pkp.exe" (undefined symbol) after a power cut or forced shutdown | Fixed in v0.12.0-beta.1 (#579): an interrupted build could leave a zeroed object file with a valid size. Set up now flushes each compiled file to disk before marking it done and automatically recompiles any damaged object file. |
| Launcher says the dump was copied in text mode | You transferred exefs/ and romfs/ over FTP in ASCII/Text mode, corrupting main, sdk, and subsdk0. Re-transfer the dump with your FTP client set to Binary mode. |
| Link Play: "the relay does not answer" when hosting or visiting over the Internet | v0.11.0 used an outdated relay IP. Update to v0.11.1, or manually enter 204.216.111.91:47610 under Link Play > Advanced > Use my own relay or address. |
| Link Play: "Communication error" (9005) when visiting an island | Both players are running copies of the same save file and have identical Player IDs. Create a separate profile under Settings > Saves > Profiles or use your own save. |
| 1-second walking/camera hitch even at high FPS | Fixed in v0.8.1+ (#276, #280): texture readbacks no longer wait a full 17 ms frame ([nvn] readback_grace_ms = 0 by default, cutting slowest readbacks from 79 ms to 6 ms), and title-screen prompt checks run every 10 s instead of every 1 s. |
| Setup stops with a file-lock error ("file cannot be opened or removed") | Move your Recompia folder out of OneDrive, Dropbox, or Desktop folders into a plain path like C:\Pokopia, and add an antivirus exclusion if real-time scanning locks newly generated object files. |
Key pkp.ini & controls.ini settings reference
pkp.ini and controls.ini sit inside your game folder next to PokopiaLauncher.exe and pkp.exe. Most options can be changed live with F1 or in the launcher, and diagnostic switches help isolate regressions:
| pkp.ini Key | Default | What It Controls |
|---|---|---|
[nvn] readback_grace_ms | 0 | Starts GPU texture readbacks immediately instead of waiting one frame (set -2 for legacy behavior; readback_log = true logs timings). |
[nvn] loop_guard | on | Prevents compute light-list shaders from walking past table bounds and triggering Vulkan device loss (#531, #533). |
[latency] vblank_lock | 0 | Set to 1 with Vsync on and a half-refresh frame cap (e.g., 45 fps on 90 Hz Steam Deck OLED) for even refresh pacing. |
[memory] limit_gb | 16 | Caps game memory allocation in GiB (works under both Windows and Linux Proton since v0.10.2-beta.3, #455). |
[pkp] pokemon_cap_limit | 31 | Sets maximum Pokémon town residents from 25 (console default) up to 64 (#524). |
[pkp] jump_momentum | 0 | Set to 1 so running jumps keep your running speed; tune with jump_momentum_strength (0.0–1.0). |
camera_shoulder_side / height | 0 / 0 | Offsets the camera (-2 to 2 blocks sideways, -1 to 2 blocks vertically) for an over-the-shoulder view (v0.10.3). |
[display] unpaced_loading | 0 | Set to 1 (or enable Fast loading screens in Settings > Game > Experimental) to uncap FPS during loading screens. |
[fs] romfs_mod | empty | Path to a layered mod directory containing top-level romfs replacements (LD_C0_R.BIN). |
How to report a bug upstream
If an issue persists on v0.11.1 or v0.12.0-beta.1, open a ticket at github.com/Dittobyte/Recompia/issues or ask in the Recompia Discord:
- Attach
pkp.logfrom the session where the problem occurred (andsetup.logif the failure happened during Set up). - On Steam Deck, ROG Ally, or Legion Go, play for ~20 minutes and click Settings > Testing > Copy handheld report (#443) to include anonymized device, driver, and frame-time telemetry.
- If a crash followed enabling a mod, test once using Start without mods (Settings > About > Troubleshooting) first.
- Never attach copyrighted game files,
build/,shader_cache/, or personal save files to a public GitHub issue.
Common questions
Why is the window black or stuttering during the first minute of play?
The game creates several pipeline state objects while running. PokopiaLauncher translates known shaders before launch and updates the cache when you exit, so the first run stutters briefly while later runs start smoothly.
Why does the launcher say my game files are from an older version?
Recompia requires Pokémon Pokopia version 2.0.1a (both the base game and the 2.0.1a update). A base 1.0.0 or 1.0.5 dump alone will not pass verification.
How do I roll back v0.11.0 threading or Vulkan submission changes for debugging?
In v0.11.0, upstream documented diagnostic rollback switches in pkp.ini: gpu_split_ms = 0 and pool_reg_skip_same = false under [nvn]; poll_wait = false, short_sleep = sleep, and early_wake = off under [kernel]; boundary_count = render under [latency]; or environment variable PKP_LOCALS=off before running Set up again.