App Crashes on Launch

If XeniOS crashes immediately after opening:

If you are not sure whether this is a setup problem or a real bug, ask in Discord first.

1. Confirm you are on a tested setup. The lowest tested combination right now is iOS / iPadOS 18.0 on A16-class hardware.
2. Re-sign the IPA — expired signing profiles are the most common cause.
3. Ensure a JIT helper is active (StikDebug). Depending on your iOS / iPadOS version and device, you may also need LocalDevVPN. Check the latest SideStore JIT guide if your current helper setup is unclear.
4. Delete the shader cache at Library/Caches/xenia/ via the Files app.
5. Reboot your device and try again.

Black Screen After Game Loads

Some titles require specific GPU settings. Try the following in Settings:

• Toggle half_pixel_offset — some games render incorrectly with it enabled or disabled.
• Try switching render_target_path between performance and accuracy.
• Enable gpu_allow_invalid_fetch_constants if the game crashes during rendering.

Check the compatibility list for game-specific notes and recommended settings.

Low Frame Rate

Performance varies by game and device. For the best results:

• Close all background apps to free up RAM.
• Set internal_display_resolution to 0 (640x480) for maximum performance, or 8 (720p, default) for a balance.
• Make sure store_shaders and metal_shader_disk_cache are both enabled (default) so shaders are not recompiled every launch.
• Try enabling metal_presenter_use_metalfx to use MetalFX upscaling — render at a lower resolution and upscale.
• Avoid charging while playing to reduce thermal throttling.

Controller Not Detected

Disconnect and reconnect your Bluetooth controller. If the issue persists, forget the device in iOS Bluetooth settings and re-pair it. XeniOS supports MFi, DualSense, DualShock 4, Xbox Wireless, and Nintendo Switch Pro controllers via the GameController framework.

Logs

XeniOS writes a log file to Documents/xenia.log. You can access it via the Files app or USB file sharing. To increase verbosity, set log_level in your config file:

# In xenios.config.toml:
log_level = 3    # 0=error, 1=warning, 2=info (default), 3=debug
log_mask = 0     # Bitmask: 1=Kernel, 2=APU, 4=CPU, 8=GPU