Troubleshooting

Troubleshooting

The exe crashes INSTANTLY when I load an env (old CPU)

_crash.txt shows code=0xc000001d (illegal instruction) → your CPU has no AVX2 (pre-2013 Intel/AMD). Download the hsr_renderer-windows-x64-compat.zip build from Releases — it runs on any 64-bit CPU. (Building yourself? The default build is already the compatible one; -DHSR_AVX2=ON is the fast opt-in.)

Also note: a Vulkan-capable GPU is required. Very old integrated GPUs (Intel HD 2500/4000 era) have no Vulkan driver on Windows — the renderer cannot run on them at all.

Menus don't show up (macOS) / UI is blank but the env renders

Fixed — this was the UI font loader only knowing Windows system-font fallbacks: launched outside the repo, no font loaded and the UI drew nothing. Update to a build newer than v0.9.9 (or pull master and rebuild). The packaged builds bundle the fonts beside the binary; keep the fonts/ folder next to it.

I still see the default foggy / blue home, not my env

The cook didn't get loaded — the shell fell back to its default. Check, in order:

• Did you install the NoRoot-Spoof APK (not Rooted-System) on a non-rooted Quest?
• Is Haven 2025 your headset's selected home environment? The spoof replaces it in place, so your env only appears where Haven 2025 would. You don't switch to a custom env — an unrooted Quest can't; the spoof simply is Haven 2025 now.
• Did the shell relaunch? Kill com.oculus.vrshell (adb shell kill $(adb shell pidof com.oculus.vrshell)) or sleep/wake the headset to force a reload.
• Was the install actually accepted? Re-run with the headset connected and read the Cook status line. A spoof install FAILED means Haven 2025 is a non-removable system app on your device — use the rooted path (Rooted-System APK) instead.

Still stuck? Find out exactly why the shell rejected it — with no root. The Logcat tab reads com.oculus.vrshell's live log over adb (no su needed) and highlights the EnvironmentSystem load result. See Diagnosing a Rejected Home — hit Reload home, then Export, and attach the report when you ask for help.

Undo the spoof / get the real Haven 2025 back

hsr_renderer.exe --restore-haven

or click "Restore original Haven 2025" in the Cook tab. This reinstalls the original from the auto-backup (Haven2025_Backup/ beside the exe) and relaunches the shell. No backup? See Restoring Haven 2025 for re-download / factory-reset options.

Black void / nothing renders (often Quest 2)

The env loaded but draws nothing. Quest 2 has a weaker/older GPU and some ported content does not yet render there. Try the same cook on a Quest 3 / Pro to confirm the env itself is good.

I fall through the floor / keep respawning / can't stand anywhere

The cooked home has no collision. A port needs at least one collider or there's nothing to stand on and you drop through the world forever. Fix it in the editor:

• Simplest: keep Auto floor collision on in the Cook tab (it's the default) and re-cook.
• Or place real collision: Scene tab → + Add → a Navmesh (walkable mesh baked from a selection) or a Box collider, then re-cook.

Newer builds pop a warning before cooking when a home would ship zero collision, so you can't ship a fall-through home by accident — if you clicked "Cook anyway", that's the cause.

INSTALL_PARSE_FAILED_NO_CERTIFICATES

The APK is unsigned. Keep Auto-sign on, or sign manually:

hsr_renderer.exe --sign <file>.apk
hsr_renderer.exe --fetch-tools     # if signing reports no build-tools (needs curl + network)

On a clean PC with no Android SDK and no Java, the first sign auto-downloads the toolchain beside the exe.

adb not found / install does nothing

Put adb beside the exe (Windows: adb.exe + AdbWinApi.dll + AdbWinUsbApi.dll; Linux/macOS: just adb — see Installation & Setup), or set HSR_ADB to your adb path. Verify with adb devices, and accept the USB-debugging prompt in the headset.

Wrong device when several are attached

Put the serial from adb devices in the Device field of the Cook tab.

Wi-Fi install drops / can't get root

Over Wi-Fi the root check (adb root) can briefly drop and reconnect the TCP session. If root detection is flaky over Wi-Fi, use a USB cable for the install.

Reporting a crash

Every crash writes _crash.txt next to the binary (all platforms — symbolized stack on Windows, backtrace on Linux/macOS). Attach it to a GitHub issue together with what env you loaded and what you clicked.

Environment variables (advanced)

Var	Effect
HSR_ADB	Path to adb (overrides the beside-the-exe / PATH search).
HSR_BUILDTOOLS	Android build-tools dir (apksigner + zipalign) if you don't want auto-detect/download.
HSR_KEYSTORE	Signing keystore (else a debug keystore is auto-generated beside the exe).
HSR_NOINSTALL	Headless/CLI cooks: skip the auto-install step.
HSR_VERBOSE	Verbose decode/cook logging to stderr.

More dev-only flags: Developer Guide.