Skip to content

Troubleshooting

Jump to bottom
Claus Valca edited this page Sep 15, 2026 · 3 revisions

🔧 Troubleshooting

"Tool not found" error

OpenROM can't find chdman, maxcso, ecm, or another bundled tool.

Fix:

  • Make sure the assets/ folder is in the same directory as OpenROM
  • If running from source, make sure you cloned the full repo including assets
  • Check SECURITY.md for SHA256 checksums to verify your download

Conversion failed mid-way

Check the terminal log first — it has the exact error from the tool.

Common causes:

  • Not enough disk space — CHD conversion needs temporary space equal to the original file size
  • Corrupted source file — try a different copy of the ROM
  • Missing CUE file — OpenROM auto-generates it for BIN files, but GDI needs all tracks present
  • Modded ISO — see "Platform detection fails" below

Platform detection fails / wrong format detected

Some modded or fan-translated ISOs have their platform magic bytes overwritten.

Fix — CLI workaround:

openrom-core --input "modded_game.iso" --format CHD --force-platform PS2

Valid platform values: PS1, PS2, PSP, GameCube, Wii, Xbox, Dreamcast, Saturn, Sega CD, PC-Engine CD, Neo Geo CD

CUE file missing

If you have a BIN without a CUE, OpenROM auto-generates one.

If it still fails, your BIN might be a multi-track game — you need all the .bin tracks + the .cue file together in the same folder.

Antivirus flagging OpenROM

This is a known false positive — see FAQ for the full explanation.

Quick fix: add OpenROM's folder to your antivirus exclusions.

Verify your download is genuine using SHA256 checksums in SECURITY.md.

🪟 Windows: "Windows protected your PC"

Click More info → Run anyway.

This is SmartScreen — OpenROM isn't signed because we're indie, not because it's unsafe. Your download is genuine if the SHA256 matches SECURITY.md.

🐧 Linux: app does nothing on double-click

The ZIP release is a folder with the OpenROM binary inside — not an AppImage.

cd OpenROM_Linux_x86_64/
chmod +x OpenROM
./OpenROM

If it still doesn't start, check for missing dependencies:

ldd OpenROM | grep "not found"

🍎 macOS: "App can't be opened" or "damaged"

Gatekeeper blocks OpenROM because it's not signed with an Apple Developer certificate.

Fix:

xattr -cr /Applications/OpenROM.app

Then right-click the app → Open → Open again.

If Finder buttons don't work or you get "Operation not permitted":

This affects the macOS ARM build before v2.7.1. The fix is already in the latest release — download it from GitHub.

If you're on v2.7.1+ and still seeing this, run:

xattr -cr /Applications/OpenROM.app
codesign --deep --force --sign - /Applications/OpenROM.app

🍎 macOS: openrom-core won't launch

If the CLI throws couldn't launch child (exec): Operation not permitted:

chmod +x /Applications/OpenROM.app/Contents/MacOS/openrom-core
xattr -cr /Applications/OpenROM.app
codesign --deep --force --sign - /Applications/OpenROM.app

Something else?

Open an issue on GitHub with:

  1. Your OS and version
  2. The OpenROM version
  3. The full terminal log from the failed conversion

Clone this wiki locally