Troubleshooting

Diagnose and fix the most common issues with Winlator containers: performance, crashes, graphics glitches, audio problems, and installation errors.

Performance issues

Poor frame rates and stuttering are the most common complaints when running Windows games on Android. Try these steps in order.

1. Switch Box64 to the Performance preset

   Open Container Settings → Advanced Tab and change the Box64 Preset to Performance. This tells Box64 to prefer speed over strict compatibility in its x86-64 translation.

2. Verify mesa_glthread is enabled

   In Container Settings → Environment Variables, confirm mesa_glthread=true is present. It is on by default but may have been removed accidentally.

3. Enable WINEESYNC

   Make sure WINEESYNC=1 is in the environment variables list. esync dramatically reduces CPU usage for synchronization-heavy applications.

4. Switch to DXVK

   In Container Settings, change the DX Wrapper from WineD3D to dxvk. DXVK translates D3D9/10/11 to Vulkan, which is much faster on Adreno GPUs with the Turnip driver.

5. Use per-shortcut settings for Unity games

   If the game uses the Unity Engine, open the shortcut settings and add -force-gfx-direct to the Exec Arguments field. This forces Unity to use a single rendering thread and can significantly improve stability and frame rate.

Application won't start

When a Windows application exits immediately, shows a crash dialog, or never opens:

1. Check the DX wrapper

   Match the wrapper to the DirectX version the game uses:

   DirectX version	Recommended wrapper
   DirectX 9 / 10 / 11	dxvk
   DirectX 12	vkd3d
   Very old DirectDraw	cnc-ddraw

2. Install Wine Mono for .NET apps

   If the application shows an error about .NET Framework or mscoree.dll:

   1. Start the container and open the Windows Start Menu
   2. Navigate to System Tools → Installers
   3. Install Wine Mono
3. Try a different Wine version

   Some applications have regressions in specific Wine releases. Install an alternative Wine version via Settings → Install Wine Version, then switch the container to use it.

4. Read Wine debug output

   Enable Wine debug logging in Settings → Enable Wine Debug. The default channels (warn,err,fixme) will surface most startup errors in the log output.

Old games display issues

Games from the early 2000s and earlier often have trouble with modern graphics stacks.

• Blank screen or immediate crash on launch: Add MESA_EXTENSION_MAX_YEAR=2003 to Container Settings → Environment Variables. This hides modern GL extensions that old games cannot handle.
• DirectDraw games (RTS, strategy): Switch the DX wrapper to cnc-ddraw (CNC DDraw). It provides a software-accelerated DirectDraw implementation tuned for classic titles.
• Low-resolution games squeezed into a corner: Open the shortcut settings and enable Force Fullscreen. This stretches the game’s output to fill the display.
• Corrupted 2D sprites or palette issues: Some very old titles expect an 8-bit color mode. Try enabling cnc-ddraw and configuring its renderer in the DX wrapper settings.

Graphical glitches or crashes in-game

Visual artifacts, flickering, or GPU-triggered crashes usually have driver-level causes.

1. Switch Box64 to the Stability preset

   In Container Settings → Advanced Tab, set the Box64 Preset to Stability. This sacrifices some speed for more conservative JIT behavior that reduces crashes in complex games.

2. Try a different graphics driver

   • Turnip (default): Adreno GPU Vulkan driver — fastest but requires an Adreno GPU.
   • VirGL: Software-based OpenGL renderer — slower but highly compatible. Use this as a fallback on non-Adreno devices.
3. Disable mesa_glthread

   If the game crashes with what appears to be a threading race condition, try setting mesa_glthread=false in environment variables. This removes the GL threading layer at the cost of some performance.

Audio problems

See the full Audio configuration page for detailed guidance. Quick checks:

• Confirm directsound=1 in Container Settings → Wine Components
• Verify the audio driver is set to alsa in Container Settings
• For MIDI music, enable directmusic=1
• For video cutscene audio, enable directshow=1

32-bit app compatibility

32-bit Windows applications require both a 32-bit Wine configuration and Box86 for x86 translation.

1. Enable WoW64 mode

   In Container Settings → Advanced Tab, make sure WoW64 Mode is enabled. This is the default setting and allows 32-bit apps to run alongside 64-bit Wine.

2. Configure the Box86 preset

   Box86 handles the 32-bit x86 instruction translation. In Container Settings → Advanced Tab, set the Box86 Preset to an appropriate level:

   • Compatibility: Best for broad support
   • Performance: Faster but may cause instability in some games
3. Check for a 64-bit version

   Many 32-bit games also have 64-bit executables in the same installation directory. Try launching the *64.exe or *_x64.exe variant if available — it will bypass Box86 entirely.

Installation or storage errors

• Winlator fails to install or initialize: Ensure at least 2 GB of free internal storage is available. The container filesystem, Wine prefix, and shader cache all require significant space.
• Storage permission denied: Grant Winlator access to external storage in Android Settings → Apps → Winlator → Permissions → Files and media.
• Cannot access D: or E: drive: The default D: drive maps to the Android Downloads folder and E: to Winlator’s internal storage directory. If either path is missing, verify the drive mapping in Container Settings → Drives.
• App crashes on install: Force-stop Winlator, clear its cache from Android Settings, and relaunch to retry initialization.

Reporting bugs

If none of the above resolves your issue, file a bug report on the official GitHub repository:

github.com/brunodev85/winlator/issues

Include your device model, Android version, Winlator version, the name of the application you are trying to run, and the Wine debug log output when filing a report. This helps maintainers reproduce and fix the issue faster.