Troubleshooting

Troubleshooting

A game won't start, or closes at once

1. Read the launch log. Show Log (in the game's menu or the workshop) opens Wine's output from the last session. Lines starting with err: are usually the useful ones; a missing DLL (Library … not found) means a runtime component is missing.
2. Try another graphics layer. In the recipe workshop, change Graphics: D3DMetal handles DirectX 12; DXMT only DirectX 10 and 11; DXVK DirectX 9 to 11; WineD3D is the most compatible and usually the slowest. Many Unreal and Unity games accept -dx11 as a launch argument to avoid DirectX 12.
3. Add the runtime it needs. A missing VCRUNTIME140_1.dll, for example, means the Visual C++ runtime: add vcrun2022 under Winetricks.
4. Change one thing at a time, save, and play again.
5. Ask the troubleshooting assistant (below): it reads the logs, the game's own logs and crash dumps, and the program, and suggests what to change.

From a terminal, distiller launch <game> --diagnose starts the game with Wine logging DLL loads, exceptions and errors, and Apple's Metal HUD showing while the game draws with Metal. --graphics, --dll and --args try another graphics layer, a DLL override or other arguments for one launch, without changing the recipe.

An install is taking a long time

The install window shows which step is running and for how long. .NET Framework components can take 30 minutes or more with nothing on screen (they compile their files during the install); fonts and newer .NET runtimes take several minutes. That's normal.

Distiller looks after two known causes of installs that never finish:

• .NET Framework's background compiler (a Windows service) never stops by itself under Wine, which used to leave installs waiting forever after .NET had installed. Distiller now notices when only that service is left and stops it (and sets it to start only when needed).
• Components are installed with Wine's fast synchronization (MSync) turned off, which .NET installers can stall under.

If a step shows no progress for a long time (an hour on a .NET step, say), cancel the install (Cancel Install…) and report it, with the install's logs (in Logs in Distiller's support folder).

An installer said it finished, but the game is missing

Many installers exit normally when they were cancelled or hit an error. Distiller checks the game's program is in the bottle afterwards; if it isn't, the game stays in your library with Finish Setup… and Distiller tells you. Remove it from the library (that removes its bottle too) and install again. If the installer showed an error, note it for a report.

A game stopped working after an update

• If Distiller saved a restore point, Roll Back (after the first session, or in the workshop's Bottle tab) puts the game back on its old Wine.
• Bottle ▸ Versions can keep the game on the versions that worked (see Per-game versions).
• Rebuild with Current Components… reinstalls it into a fresh bottle (see Rebuilding a game's bottle).

"The drive isn't connected"

A game used in place from another drive, or Wine builds and bottles kept on an external drive, need that drive. Connect it and the game is ready again. Distiller never runs a game against a missing drive, or creates folders in place of a disconnected one.

Screenshots don't capture during a community check

Capturing needs Screen Recording permission: System Settings ▸ Privacy & Security ▸ Screen & System Audio Recording, then allow Distiller (the check's panel has Open Privacy Settings). The game's own screenshot key works too; the check collects those.

Known issues

• Battle.net's client doesn't open under the current Wine builds (Wine 11): it installs, but its main window never appears (Wine itself crashes in it). The same happens on Linux with Wine 11. A different Wine build is the likely fix; this is being looked at along with launchers.
• A Battle.net-style installer can't reach its helper (error BLZBNTBTS0000005C) when run from Wine's view of the Mac (Z:). Distiller now runs installers from the Windows user's Downloads folder on C:, which fixes it.

The AI troubleshooting assistant

Getting a Windows game to run well can take some detective work. Distiller includes a troubleshooting assistant for the AI app you already use (Claude, ChatGPT, or a model on your Mac in LM Studio or Ollama). It's an MCP server (distiller mcp) with read-only tools:

Tool	What the assistant uses it for
list_games	Your library: each game, its recipe and graphics layer, and whether it can be played.
get_game	A game's recipe and its settings for your Mac.
read_launch_log	Wine's output from a launch, filtered (for example to err: lines).
list_game_logs	Logs and crash dumps the game writes itself.
read_game_file	One of those logs, or a text config file.
inspect_program	A program's details without running it: 32- or 64-bit, imported DLLs, DirectX version, engine, suggested settings.
get_environment	Your Mac and the installed Wine builds and graphics layers.

It can't change, run or delete anything, only reads a game's own folder and bottle, and shows paths in your home folder as ~.

Turn it on: Settings ▸ AI Assistant ▸ Let AI assistants troubleshoot games. The Connect an AI Assistant window opens with the steps for each app, filled in with the command for your Mac (Connection Steps… opens it again). Your AI app starts the server itself when it needs it; it talks only over standard input and output and never listens on the network. Turn the switch off when you're done: connected assistants lose access at once.

From a terminal: distiller assistant on and distiller assistant setup <app> (claude-desktop, claude-code, chatgpt, lm-studio, ollama or other).

Where your data goes: with Claude or ChatGPT, what the tools return (log lines, file contents, your Mac's setup) is sent to that service, under its privacy terms. With a model in LM Studio or Ollama, everything stays on your Mac. Your AI app asks before each tool call.

The website's troubleshooting assistant guide has step-by-step setup for each app and a worked example.

Getting help

Open an issue with what you did, what happened, your Mac (the summary at the bottom of Distiller's sidebar) and the relevant log. Logs are in ~/Library/Application Support/Distiller/Logs; check them for anything private before attaching.