Troubleshooting

Find the symptom, then follow the fix. If nothing matches, collect the diagnostic report and file a bug report.

Startup

Permission denied when running the AppImage

The file is not executable. Run chmod +x OpenBox-$(uname -m).AppImage, then start it again.

The AppImage does not mount

Install the FUSE 2 library, or run the AppImage with --appimage-extract-and-run. The AppImage section lists the package names.

The window does not open

Start OpenBox from a terminal and read the error it prints. To use the browser interface instead, run openbox --web or python3 web_app.py, then open the printed address.

If the printed address has no token, read server.token from the data folder and add it to the address as ?token=<value>. For API calls, send the value in the X-OpenBox-Token header instead. Treat any URL that contains the token as a password.

python3: command not found or ModuleNotFoundError when running from source

OpenBox needs Python 3.10 or newer. Run it with python3 on Linux and macOS, or with python on Windows. The Python that ships with macOS Command Line Tools can be older than 3.10. Install a current one with brew install python@3.12.

running scripts is disabled on this system on Windows

Run the installer with a one-time policy bypass:

powershell -ExecutionPolicy Bypass -File .\OpenBox\scripts\install.ps1

The bypass applies only to that command.

Windows opens a browser window instead of a native window

The native window needs the WebView2 runtime. Windows 11 and most Windows 10 systems include it. Without the runtime or the native host file, OpenBox opens the same interface in a browser app window.

macOS blocks the first launch

Open System Settings > Privacy & Security and choose Open Anyway. The bundle is not notarized, so each new build asks again.

Library

The library looks empty after install

OpenBox reads OPENBOX_DATA_DIR at startup. If you edited a different folder, OpenBox reads another one. Set the variable in the environment before launch.

A game is missing after import

Check the folder path. Use the full path, such as /home/you/test-game, because a wrong path imports nothing and OpenBox reports it. Scan the folder again. Re-scanning never duplicates an entry.

Resetting the library

Copy library.json somewhere safe first. Then delete it from the data folder. The library resets, and media files stay.

Launching

PLAY is disabled with has no launch command and its file is not executable

Make the file executable with chmod +x, or assign an emulator profile to the game's platform. A Windows .exe needs no permission bit.

The configured path no longer exists

The file moved or was deleted. Edit the game and point it at the new path, or import the folder again.

Set a launch command for the platform

The platform has no emulator profile yet. Set one, as described in the emulator guide. On Linux, Launch check can install missing Flathub emulators. On Windows and macOS, install the emulator yourself and point the profile at its executable.

ROM files do not launch

ROMs need an emulator profile for their platform. Set the profile first. Until then, OpenBox shows a Launch check notification.

The session reports Session failed with an exit code

The game process exited with a non-zero code. Check the launch command and the emulator installation. The History entry records the exit status.

Flatpak cannot read Steam or ROM folders

The Flatpak bundle can read folders under your home directory. Keep game folders there.

Diagnostics

What to send with a report

Open Settings, then Library Audit, and use the diagnostic log. Or copy the error banner's Copy details output, which includes a request ID that maintainers can match to the log. The diagnostic report is redacted and stays local until you share it.

See also: Reporting issues and FAQ.