Troubleshooting

Getting Help

Before contacting support, try these steps:

• Check the Getting Started guide for setup basics
• Search GitHub Issues for known problems
• Ask the community on GitHub Discussions

Installation Issues

App Won't Open

Symptom: TruchiEmu bounces in the dock but doesn't launch, or shows "TruchiEmu cannot be opened because it is from an unidentified developer."

Solution: macOS may block apps not notarized by Apple. Right-click (or Ctrl-click) the app and select "Open" from the context menu, then click "Open" in the dialog. Alternatively, go to System Settings > Privacy & Security and look for a message about TruchiEmu being blocked.

App Crashes on Launch

Symptom: TruchiEmu crashes immediately after launching.

Solution: Verify your macOS version is 14.0 (Sonoma) or later. Use the built-in Environment Diagnostics tool in Settings to check for hardware compatibility issues. If the app won't open at all, try deleting the preferences file at ~/Library/Preferences/com.truchiemu.plist.

Missing Dependencies

Symptom: Error messages about missing libraries or frameworks when building from source.

Solution: Ensure Xcode Command Line Tools are installed (xcode-select --install). Install required dependencies with Homebrew: brew install cmake xcodegen.

Performance Issues

Low Frame Rate / Stuttering

Symptom: Games run below full speed or have frequent stutters.

Solution: Try these steps in order:

1. Reduce shader complexity or use Passthrough shader
2. Lower internal resolution scaling (for 3D systems like N64, PSP)
3. Increase audio buffer to 128-256ms
4. Enable frame skipping (1-2 frames max)
5. Close other applications to free system resources
6. For N64: try a different graphics plugin (GLideN64 vs Angrylion)

Audio Crackling or Popping

Symptom: Distorted audio, especially during scene transitions or complex audio sequences.

Solution: Increase audio buffer size in Settings > Audio. Try 128ms or 256ms. Disable "Reduce Audio Latency" if enabled. For DSP-heavy games (Pilotwings, Super Mario Kart), use snes9x core with audio fix enabled.

High CPU Usage

Symptom: TruchiEmu uses excessive CPU even when idle or on simple games.

Solution: Disable threaded rendering if enabled on single-core systems. Use lighter emulation cores (fceumm instead of mesen for NES, snes9x instead of bsnes for SNES). Disable rewind feature if not needed. Reduce runahead frames to 0 or 1.

Controller Issues

Controller Not Detected

Symptom: Controller connected but not recognized by TruchiEmu.

Solution: Check macOS System Settings > Privacy & Security > Bluetooth (for wireless). Ensure the controller is paired before launching TruchiEmu. For Xbox controllers, try a wired USB connection first. Restart TruchiEmu with the controller connected.

Input Lag

Symptom: Delay between pressing a button and the action appearing on screen.

Solution: Use a wired connection instead of Bluetooth. Reduce audio buffer size. Disable V-Sync or enable "Hard GPU Sync" with 0-1 frames. Reduce runahead to 1-2 frames for responsive input.

Wrong Button Mapping

Symptom: Buttons don't match the expected layout.

Solution: Open Settings > Controllers > Button Mapping and remap buttons as needed. Save as a profile for reuse. Check if a per-core or per-game override is active.

Analog Stick Drift

Symptom: Character moves without touching the controller.

Solution: Increase deadzone to 15-20% in controller calibration settings. Run the calibration wizard to detect center position. Clean controller sticks with compressed air.

Shader Issues

Shader Compilation Failures

Symptom: "Metal compiler error" when selecting a shader.

Solution: Update macOS to the latest version for newest Metal features. Verify your GPU supports the required Metal feature set (requires macOS 14+).

No Visible Effect

Symptom: Shader is selected but no visual change is visible.

Solution: Some shaders have subtle effects. Check shader intensity sliders in settings. Try a more noticeable shader like CRT-Royale to verify the system works.

Shader Performance Impact

Symptom: Frame rate drops with complex shaders enabled.

Solution: Use simpler shaders (Lite CRT instead of CRT Multipass, ScaleFX instead of xBRZ). Reduce shader chain complexity. Consider using per-game shader settings to use light shaders for demanding games.

ROM Loading Issues

ROM Not Recognized

Symptom: Game shows as "Unknown" or doesn't appear in library.

Solution: Verify the ROM file type is supported by the target system. Check that the file extension is in the allowed list. Try a different ROM dump from a verified source. Manually identify the game via right-click > Identify Game.

Game Won't Launch

Symptom: Game appears in library but crashes on launch.

Solution: Ensure you have the correct core installed for the system. Check if the game requires BIOS files (PlayStation, Saturn, Neo Geo). Try a different emulation core. Verify the ROM is not corrupted.

Wrong System Detected

Symptom: Game launches with wrong emulator core.

Solution: Right-click the game and select "Edit Metadata," then correct the system assignment. You can also set per-system default cores in Settings > Cores.

Save State Issues

Save States Won't Load

Symptom: Save state appears in browser but fails to load.

Solution: Ensure you're using the same core version that created the save. Save states are not compatible across different cores. Check that the save file isn't corrupted by verifying its checksum.

Cloud Sync Conflicts

Symptom: Error messages about conflicting save states across devices.

Solution: Review conflict resolution settings in Save State preferences. Manually resolve conflicts in the sync dashboard. Use different slot banks for different devices.

Reporting Bugs

When reporting issues on GitHub, please include:

• Your macOS version and hardware (Apple Silicon or Intel)
• TruchiEmu version number
• The emulation core and game you were using
• Steps to reproduce the problem
• Any error messages or crash logs
• Screenshots or screen recordings if applicable

Crash logs can be found in: ~/Library/Logs/DiagnosticReports/