SHIP OF HARKINIAN / MAC RECOVERY
Ship of Harkinian on Mac: issues and fixes
Start with the app version and the point where it stops. The cases below retain the specific versions from the original reports.
Choose a case below to see its steps.
A macOS security alert, ROM extraction failure and controller crash need different steps. For a system alert, use the first-open guide. For an in-game or launcher failure, choose a case below.
Mac cases by version
Crashes when a controller connects or disconnectsOpen report · SoH 9.0.0 · macOS 15.4 / M1 Pro
Issue #5342 reports crashes when controllers are added or removed. It names Xbox Elite Series 2, Switch Pro and Brawler64 v2 on an M1 Pro Mac.
Narrow it down
- Quit the game, connect the controller in macOS first, then reopen the game.
- Compare that with a keyboard-only start. Avoid reconnecting the controller during the comparison.
- Record the exact game version, controller and connection type if it still crashes.
Does a start with an already-connected controller differ from hot-plugging? This is an isolation step, not an upstream-confirmed fix.
“Symbol not found: _kIOMainPortDefault”Open report · SoH 9.2.3
Issue #7214 found that bundled libraries targeted a newer macOS than the app’s advertised minimum. The report inspected binaries; it did not test an actual macOS 10.15/11 machine.
- Check the macOS version in About This Mac.
- Record the exact release ZIP you installed and the missing-symbol message.
- Check current release requirements before trying a replacement package.
Reinstalling the same package or changing ROMs does not change a missing system-library symbol. Do not treat the old bundle’s minimum-version label as proof of compatibility.
Crashes while generating OTRClosed report · SoH 9.2.0 · macOS 26.3.1
Issue #6402 describes a crash immediately after agreeing to first-run extraction. It names 9.2.0, rather than every Ship of Harkinian release.
- Verify the ROM against the supported-hash list.
- Keep any existing saves and settings before changing the app.
- Try the stable release in the installation guide and let it perform its own extraction.
Extraction finishes and the title appears. The closed report alone does not establish a fix for every later extraction failure.
An older launcher stops in a folder containing spacesClosed report · legacy shell launcher
Issue #4180 reports a launch failure under a path such as Applications/Game ports, while a simpler Applications path worked. A contributor later says the Game Mode implementation removed the shell launcher responsible.
- Check whether you are using an old package.
- Use the current stable app in Applications.
- Keep your data backup; avoid rewriting the app’s executable using an old workaround.
The app reaches first-run or the title from its installed location.
Crashes when entering fullscreenClosed report · SoH 9.0.5 · macOS 26 beta
Issue #5764 contains a fullscreen crash in that particular app/system combination.
- Start windowed and check whether the game otherwise works.
- Record the app and macOS versions before comparing fullscreen.
- If trying another graphics backend, change it in Settings, restart, then repeat the same check.
Distinguish a fullscreen-only failure from a crash before the title. A different backend is a diagnostic comparison, not a guaranteed repair.
ROM rejected rather than app crashed?
Return to ROM verification. Match the hash and region supported by the installed release. Repeatedly renaming an unsupported ROM will not change its contents.
A first-start data-generation notification is expected. A macOS “developer cannot be verified” alert occurs earlier and belongs to the system-warning path.
Keep a useful reproduction
- Ship of Harkinian version and original package name.
- Mac model, chip and macOS version.
- Whether failure occurs before the window, during ROM extraction or while playing.
- Controller model and connection type if involved.
- The first error and whether the same action works without mods.
Compare against the original issue before reporting a new symptom to the project. This page does not send reports or upload your files.