Troubleshooting
Problems we have hit, why they happen and how to fix them. This page grows with every release.
Game crashes with "Error compiling shader file"Fixed since 0.1.8
Symptom
While playing, a box says "Error compiling shader file … E4002: Failed to open …", then the game crashes and offers to collect crash files.
Cause
When a scene needs a shader that is not prebuilt, the game compiles it. Wine used its own shader compiler instead of the Microsoft one that ships with the game, and Wine's compiler could not open the shader's include files.
Fix
- Update kegPlay to the latest version. Since 0.1.11 kegPlay makes every game that ships Microsoft's shader compiler (d3dcompiler_47.dll) use it, as soon as the game finishes downloading.
- The first time a new shader is needed the game may pause for a few seconds. That is normal.
- If the game offers Safe Mode on the next start, choose No to keep your graphics settings.
Game crashes when entering play, log says "Null program bound" or "E5016"Fixed since 0.1.14
Symptom
The game reaches its menu but crashes when play starts (e.g. Kenshi on New Game) with Wine's "page fault on execute access" box. The game's log shows "Cannot compile … E5016: Object of type 'Texture2D' must be bound to register type 't'" and then "Null program bound".
Cause
Wine's shader compiler is stricter than Microsoft's and rejects the game's shaders, so the game has none to draw with and crashes. The game ships Microsoft's compiler (e.g. D3DCompiler_43.dll in Kenshi), but kegPlay before 0.1.14 only used version _47.
Fix
- Update kegPlay to 0.1.14 or later. kegPlay makes the game use the Microsoft compiler it ships (any d3dcompiler_NN.dll) when you press Play or open Steam.
- Start the game again; nothing else is needed.
Cannot sign in to Steam, the QR code never appearsFixed since 0.1.0
Symptom
The Steam sign-in screen shows a blurred QR box with a reload icon, or signing in with a password spins forever.
Cause
Some ISPs' DNS servers answer "no such name" for Steam's sign-in servers (steamserver.net). Steam for Windows asks the system DNS directly and does not go through the unblocker.
Fix
- Update kegPlay: the app ships a DNS fallback that asks 1.1.1.1 when the system DNS says the name does not exist.
- Click Stop Steam, then Open Steam to apply it.
- Temporary workaround: set your Mac's DNS to 1.1.1.1 in System Settings › Network.
Steam opens as a black windowFixed since 0.1.13
Symptom
The Steam window appears but is completely black, with no buttons or game list.
Cause
Steam's interface is an embedded browser whose GPU acceleration does not work in Wine on a Mac.
Fix
- kegPlay patches this every time it opens Steam, and since 0.1.13 it re-applies the patch when Steam updates itself (Steam closes and reopens once).
- If it is still black: click Stop Steam, wait a few seconds, then Open Steam.
Installing a game says "No internet connection"
Symptom
Steam inside kegPlay is signed in, but installing a game reports no connection.
Cause
Steam for Mac is running with the same account. The two clients fight over one session and the one inside kegPlay is kicked out.
Fix
- Quit Steam for Mac completely (Cmd+Q).
- In kegPlay click Stop Steam, then Open Steam.
Movement keys type into a white box and the character stuttersFixed since 0.1.0
Symptom
In a game, pressing W A S D shows a white box with text like "wddddaw" in a corner of the screen.
Cause
A macOS input method (Vietnamese Telex/VNI, Chinese, Japanese, Korean) is active. It holds keys back to compose text.
Fix
- Keep the kegPlay app open while you play: it switches the keyboard to ABC when a game window becomes active and restores your input method when you leave.
- Check the "Switch keyboard to ABC while in a game" switch in the app's Settings.
- Or switch to the ABC keyboard yourself before playing.
"Could not create OpenGL context" when starting a gameFixed since 0.1.0
Symptom
Clicking Play shows "Graphics driver error: Could not create OpenGL context". Seen with Mount & Blade II: Bannerlord.
Cause
The game's launcher asks for OpenGL in a way Wine on macOS refuses, even though macOS can provide it.
Fix
- Select the DXMT engine in kegPlay (the fix only exists for DXMT).
- Click Stop Steam, Open Steam, then start the game again.
An old game says "Unable to set the video mode", flickers or stays blackFixed since 0.1.5
Symptom
Starting the game shows "Error - Unable to set the video mode", or the game window flickers black, or nothing appears. Seen with Red Alert 2 / Yuri's Revenge and other old DirectDraw games.
Cause
The game demands a 640x480 or 800x600 full-screen mode. Mac displays do not offer those modes, and Wine's DirectDraw on macOS does not draw this kind of game reliably.
Fix
- Update kegPlay to the latest version. For supported games (currently Red Alert 2 and Yuri's Revenge) kegPlay applies the fix when you click Open Steam or Play; there is nothing for you to do.
- The game runs in a window at your screen's resolution: menus sit in the centre of the window and battles fill the screen.
- Do not pick a smaller resolution in the game's Options and do not drag the window's corner to resize it: menu buttons end up misplaced or missing. If that happens, quit the game and press Play again from kegPlay.
- Another old game shows this error and is not supported yet: tell us its name on GitHub so we can add it.
A game's launcher flickers blackFixed since 0.1.0
Symptom
The launcher window alternates between its picture and solid black several times a second. Seen with Bannerlord.
Cause
The launcher draws with OpenGL and copies the image to a transparent window. Wine on macOS showed both layers on top of each other.
Fix
- Update kegPlay and select DXMT.
- A black flash of under a second right at start is still normal.
"Failed to load steamui.dll"Fixed since 0.1.0
Symptom
The first time Steam opens after setup, this error box appears and Steam quits.
Cause
Steam had not finished downloading its own core files on first run.
Fix
- Current versions handle this: on first run kegPlay lets Steam download everything, then reopens it. The first start can take a few minutes.
- On an older version: click Open Steam once more.
The Store page is blank or does not loadFixed since 0.1.15
Symptom
The library works but the Store tab is blank, or shows "Something went wrong while displaying this content… Unable to preload CSS for https://store.fastly.steamstatic.com/…"; Workshop images do not load.
Cause
Your ISP blocks store.steampowered.com and, since November 2026, also Steam's image/CSS servers (*.steamstatic.com, steamusercontent.com, akamaihd.net). In version 0.1.0 a bug also made the "Unblock Store" switch have no effect.
Fix
- Update to kegPlay 0.1.15 or later (it also routes the image/CSS servers through the unblocker).
- Turn on "Unblock Store" in kegPlay.
- Click Stop Steam, then Open Steam (applies from the next start).
macOS refuses to open kegPlay
Symptom
On first launch macOS says the developer cannot be verified.
Cause
kegPlay is not signed with an Apple Developer account (it is a free project and has not bought one).
Fix
- Open System Settings › Privacy & Security, scroll down and click "Open Anyway" for Kegplay.
- You only do this once. The source is public on GitHub if you want to inspect it.
Game needs DirectX 12
Symptom
kegPlay shows "Needs DirectX 12 — not supported yet" under the game, or the game says DirectX 12 is missing and quits.
Cause
kegPlay translates DirectX 9, 10 and 11 to Metal. On the Mac, DirectX 12 translation currently exists only in Apple's toolkit, which kegPlay is not allowed to redistribute.
Fix
- If the game can start in DirectX 11 mode (often a Steam launch option: right-click the game › Properties › Launch Options, for example -dx11), try that.
- Otherwise this game cannot be played with kegPlay yet.
DirectX 9 game runs slowly
Symptom
kegPlay shows "DirectX 9 game — may run slowly" under the game; it starts but stutters or has low FPS.
Cause
DXMT handles DirectX 10 and 11 only. DirectX 9 games go through WineD3D, which translates to OpenGL, and OpenGL on the Mac is old and slower.
Fix
- Lower the resolution and graphics quality in the game.
- Report the game in GitHub Issues so it can be prioritised.
Game has anti-cheat
Symptom
kegPlay shows "Has anti-cheat — online play may not work"; single-player may still run.
Cause
Anti-cheat software (Easy Anti-Cheat, BattlEye…) inspects Windows deeply and usually refuses to run under Wine.
Fix
- Try single-player or an offline mode if the game has one.
- Online play needs the game's developer to allow Wine/Proton; kegPlay cannot get around it.
Game crashed and kegPlay does not know why yet
Symptom
The game closes by itself; kegPlay shows "<game> closed unexpectedly" with a Report on GitHub button.
Cause
Wine caught an error inside the game (usually a bad memory access) that kegPlay does not recognise yet.
Fix
- Click Report on GitHub. The report is pre-filled with your kegPlay, macOS and chip versions, the game and a log excerpt; your account name and personal paths are removed. Check it, add what you were doing, then click Submit.
- Meanwhile, try switching DXMT ↔ DXVK and start the game again.
- Each problem that gets solved becomes a new rule, and the next kegPlay release handles it for everyone.
A Windows component the game needs is missing
Symptom
The game does not start or crashes at once; kegPlay says "A Windows component the game needs is missing".
Cause
The game needs a Windows library (often Visual C++ or .NET) that is not in the bottle. Steam normally installs it on first launch, but that step is sometimes skipped.
Fix
- In Steam: right-click the game › Properties › Installed Files › Verify integrity, then start the game again so Steam reinstalls its prerequisites.
- If it still fails, click Report on GitHub; the report already names the missing library.
Your problem is not here? Report it on GitHub
kegPlay