Troubleshooting

Start with doctor

grapple doctor looks at the install as a whole — not at one game — and prints one line per check. It changes nothing, so it is always safe to run.

$ grapple doctor
OK    rosetta: Rosetta 2 is running
OK    disk: 130 GB free
WARN  engines: none installed (run: grapple engine install grapple-wine)
OK    d3dmetal: not installed (graphics=auto uses DXMT; install it for DirectX 9-12)
OK    steam-wrapper: /Applications/Grapple.app/Contents/Resources/steamwebhelper.exe
OK    partial: no leftover partial engine copies

Every warning carries the command that fixes it. doctor exits 0 whatever it finds, so in a script use --json and read the ok field instead of the exit code — see doctor --json.

What each check means

Rosetta 2

Windows games are x86 programs, and an Apple Silicon Mac needs Rosetta 2 to run them. Without it the CLI stops before doing anything:

$ grapple list
grapple: Rosetta 2 is required: softwareupdate --install-rosetta --agree-to-license

doctor is deliberately exempt, so it can still run and tell you this is what is missing. Run the command it suggests once; it takes a moment and never has to be repeated.

Stopping a stuck game

A game that will not quit, a launcher stuck on a splash screen, an environment that refuses to be renamed because something is still running in it — all the same command:

$ grapple kill games
==> Stopped everything in 'games'

It only touches that one environment. Anything running in another keeps going. If nothing was running you get ==> Nothing running, which is also how you confirm an environment really is idle before duplicating or renaming it.

Where the logs are

Each environment keeps its own logs. grapple info <bottle> prints the folder, and grapple open <bottle> opens the C: drive next to it in Finder.

Logs are plain text and are overwritten each run, not appended, so look at them before starting the game again. If you want more from Wine itself, set winedebug for that environment — see the settings table — and remember to unset it afterwards, because it slows everything down and fills the log.

Diagnostics reports

grapple report puts everything above into one zip and prints where it wrote it. Run it for the environment the failing game is in, soon after the failure, while the logs still describe it.

$ grapple report games
==> Collecting diagnostics for 'games'
==> Wrote /Users/you/Desktop/grapple-report-games-20260923-101500.zip
/Users/you/Desktop/grapple-report-games-20260923-101500.zip

The zip holds:

• grapple.conf — the environment's settings, exactly as stored.
• system.txt — Grapple, Wine and macOS versions, the graphics layer in use, which D3DMetal is installed, Mac model, architecture, memory, GPU, whether Rosetta is running, free disk space, the engines you have and the Windows profiles in the environment.
• logs/ — Grapple's own logs for that environment, each trimmed to its last 5 MB.
• steam/ — the tails of the Steam client's logs, if Steam is installed there. They grow without limit, so only the last megabyte of each is taken.
• game-logs/ — Unreal and Unity logs and crash reports touched in the last week, newest first, until a 20 MB budget runs out.

Use --out to put it somewhere other than the Desktop. The command prints the path on standard output and its progress on standard error, so zip=$(grapple report games 2>/dev/null) gives you just the file name.

What to send us

Four things, and we can usually work it out without a conversation first:

1. The zip from grapple report <bottle> for the environment the game is in.
2. The game's name, and how you installed it.
3. What you did and what happened — an error message or a screenshot of the window beats a description.
4. The output of grapple doctor, if you did not already get the report to include it.

Send it the way the support page describes. If a game fails on one graphics layer, it is worth saying whether you tried another — grapple set <bottle> graphics d3dmetal and back again is a minute's work and tells us a lot.