Troubleshooting & Error Codes
Exact meanings for rerac-extract error codes 10–99, runtime exit codes 2–101, log paths, and verified fixes from re-rac/rerac and re-rac/rerac-launcher.
- Extractor codes 10–99
- Runtime exits 2 / 3 / 4 / 101
- Timestamped rac1 logs
- Verified GitHub workarounds
Where to find ReRAC log files
Before troubleshooting any setup failure or crash, open your log directory via Help → Logs folder or Settings → Folders → Open logs inside ReRAC Launcher:
- Windows:
%LOCALAPPDATA%\rerac\logs(C:\Users\<Name>\AppData\Local\rerac\logs) - Linux / SteamOS:
~/.local/share/rerac/logs(or$XDG_DATA_HOME/rerac/logs) - macOS:
~/Library/Application Support/rerac/logs
Each job writes a timestamped file: extract-rac1-<time>.log (ISO installation), verify-rac1-<time>.log (integrity check), export-rac1-<time>.log (asset export), and rac1-<time>.log (gameplay stdout/stderr with exact CLI flags on the first line and exit code on the last).
ISO extraction error codes (10 through 99)
| Code | Extractor Meaning | How to Fix |
|---|---|---|
10 | Image cannot be opened/read, or file is truncated | Verify the file exists, is not locked by another program (such as PCSX2 or a torrent client), and has the full ~4.4 GB DVD byte length. |
11 | Not a plain ISO9660 image (.bin, .chd, .cso, .zso) | Convert or re-dump your disc as a standard 2048-byte-sector .iso. Raw 2352-byte .bin tracks and compressed chdman archives are rejected. |
20 | Unknown disc (not Ratchet & Clank) | Select your 2002 Ratchet & Clank PS2 disc image. |
21 | Unsupported region, revision, or sequel | Only North American NTSC-U SCUS-97199 v1.00 works today. PAL (SCES-50916), Japanese (SCPS-15037), and sequels (R&C 2 / 3 / Deadlocked) return code 21. |
30 | Write failure in target directory | Check folder permissions on your launcher data root, or move the folder under Settings → Folders to a user-owned directory. |
31 | Insufficient disk space | Free at least 4.5 GB (plus temporary staging headroom) on the drive holding your rerac folder. |
40 | SHA-1 file verification mismatch | One or more sectors in your ISO are corrupted or modified. Open extract-rac1-<time>.log to see the exact bad file and make a clean dump from your disc. |
99 | Internal extractor or CLI usage error | Attach extract-rac1-<time>.log when reporting the error upstream. |
Startup & runtime exit codes (2, 3, 4, 101)
| Exit Code | Launcher Message / Symptom | Resolution |
|---|---|---|
Exit 2 | "ReRAC couldn’t start." (--data-dir missing argument) | Launcher/engine contract mismatch: update ReRAC Launcher to v0.3.1-alpha and Engine to v0.3.9-alpha. |
Exit 3 | "The game data is missing or incomplete." | toc.bin or extract-info.json is missing in games/rac1/data/. Click Re-extract and let extraction finish to 100%. |
Exit 4 | "The game data doesn’t match this ReRAC version." | extract-info.json has an older data_format integer than the active engine’s manifest. Click Re-extract. |
Exit 101 / signal | Window closes unexpectedly during play | Rust panic (101) or GPU driver fault. Click Open logs and attach rac1-<time>.log to a bug report. |
Verified fixes for common Windows, Linux & macOS issues
1. Black or purple window on Windows startup
Update your engine build to v0.3.9-alpha. Two separate startup bugs in earlier alphas caused blank windows on Windows PCs: a 3-thread Bevy pool deadlock on Vulkan in v0.3.1-alpha (fixed in v0.3.2-alpha) and a first-launch purple/black screen before settings.toml existed (fixed in v0.3.5-alpha). If an older laptop with Skylake-generation Intel HD 520 graphics still fails to open a window (Launcher Issue #11), install the latest Intel graphics driver with Vulkan 1.2 / DirectX 12 support.
2. Game runs in fast-forward or high input latency
Monitors that did not enforce 60 Hz VSync caused pre-v0.3.6 builds to run above 60 ticks per second; v0.3.6-alpha added wall-clock frame pacing. If you experience VSync input lag on desktop (Issue #51), test borderless fullscreen (F11) or launch with RC_NOVSYNC=1 to compare driver presentation latency.
3. macOS says ReRAC Launcher is blocked or cannot be verified
Right-click ReRAC Launcher.app in Finder and choose Open, or permit it in System Settings → Privacy & Security → Open Anyway. Always install engine ZIPs through ReRAC Launcher’s Install from zip… button rather than unpacking with Finder’s Archive Utility by hand, because the launcher strips Apple’s com.apple.quarantine attribute from rerac and rerac-extract automatically.
4. Controller not responding (DualSense Bluetooth on macOS / 8BitDo on Linux)
On Linux, update to v0.3.8-alpha or v0.3.9-alpha for multi-controller support and the 8BitDo Ultimate button fix. On macOS (Launcher Issue #5), switch a DualSense from Bluetooth to USB-C if inputs are ignored. On third-party multi-mode pads (Launcher Issue #8), set the controller’s physical mode switch to XInput.
Recommended PC controllers
ReRAC maps PlayStation 2 face buttons, bumpers, triggers and twin analog sticks by physical position across connected gamepads, with multi-controller detection and Linux 8BitDo mapping fixes in v0.3.8-alpha:
| Controller | Best For in ReRAC | Hardware Advantage | Link |
|---|---|---|---|
| Sony DualSense | Authentic PlayStation button layout | Symmetrical twin sticks matching DualShock 2 muscle memory + crisp D-pad | View on Amazon |
| 8BitDo Ultimate 2 Wireless | Linux, SteamOS & Windows desktop | Zero-drift TMR sticks, charging dock, verified Linux button mapping in v0.3.8-alpha | View on Amazon |
| GameSir Cyclone 2 | Precision 3D platforming & strafing | TMR sticks, hair-trigger locks for L2/R2 Thruster-Pack strafing, 1000 Hz wireless | View on Amazon |
| Xbox Wireless Controller | Plug-and-play Windows 10/11 | Native Windows XInput standard with positional face-button mapping | View on Amazon |
As an Amazon Associate, this site earns from qualifying purchases.
Common questions
Why does "Something went wrong, setup did not finish" appear during ISO install?
Reported in Launcher Issue #10: click Details or open the newest extract-rac1-<time>.log file. In nearly every case the exit code at the bottom is 11 (compressed .chd/.cso or .bin instead of plain .iso), 21 (PAL SCES-50916 disc instead of NTSC-U SCUS-97199), or 31 (less than 4.5 GB free on C:).
Does cancelling Install via ISO leave half-extracted files behind?
No. ReRAC Launcher extracts into games/rac1/data.staging/ and deletes the staging directory immediately if cancelled or if verification fails.