Highball › Troubleshooting Highball on macOS

Troubleshooting

"Highball can't be opened because Apple cannot check it for malicious software"

Every Highball release since 0.1.0 is signed with an Apple Developer ID and notarized by Apple. If you see this warning, the copy on your disk is not the copy that was published.

The usual cause is a third-party unarchiver. Sparkle, the update framework Highball uses, contains symbolic links inside its framework bundle. Some unzip tools write those links out as ordinary files instead, which breaks Apple's code signature, and macOS correctly refuses to open a bundle whose seal no longer matches. The file was fine when it left the server. The extraction broke it.

The fix: download Highball.dmg rather than the zip, and open it by double-clicking. The DMG is notarized and stapled, it needs no extraction tool, and it is the download every link on this site points to.

If you already have a broken copy, delete it, empty the Trash, and download the DMG again. Safari, Finder's Archive Utility, and ditto all handle the zip correctly if you prefer it; unzip and several popular third-party unarchivers do not.

The engine download stalls or never finishes

Highball reports live progress while it downloads an engine. If the progress stops moving for a minute, the transfer has stalled rather than hung: cancel it and start again, and it will resume. Partially downloaded engines are cleaned up automatically on the next attempt, so a failed install never leaves anything broken behind.

Steam takes a very long time on first run

Steam updates itself the first time it launches inside a fresh bottle, and that first update is genuinely slow, often around twenty minutes. Highball shows this as a stage banner so you know the wait is expected. Leave it alone until it finishes. Later launches are normal speed.

A game launches to a black screen

Usually the renderer. Highball can run each game through DXVK, DXMT or Apple's D3DMetal, and titles differ in which one they tolerate. Check the game's page in the database for the renderer that has actually been confirmed, then set it in the bottle's settings. If you find one that works where the database says nothing yet, send a report.

The game refuses to start because of anti-cheat

If it uses kernel-level anti-cheat, it cannot be made to work. Here is why, and what your options are.

Something else

Open an issue on GitHub or ask in Discussions. The app can prefill a bug report for you from the Help menu, including the log, which makes it much faster to diagnose.