// OPENBOX DOCS
Troubleshooting diagnostic logs
Read, copy, and share the rotating diagnostic log safely.
The diagnostic log is the first place to look when anything misbehaves. It records server activity, import/launch/session errors, job failures, and provider errors with credentials redacted.
Where it lives
- Path:
<data-dir>/openbox.log(default~/.local/share/openbox-game-launcher/openbox.logon Linux,%LOCALAPPDATA%\openbox-game-launcher\openbox.logon Windows, and~/Library/Application Support/openbox-game-launcher/openbox.logon macOS). - Rotation: 2 MiB per file, 4 rotations (
openbox.log.1....4). - Redaction: tokens, passwords, secrets, API keys, and authorization values are redacted before writing.
- It can still contain game names and local file paths, review it before sharing.
Copy it
Settings > Advanced > Copy diagnostic log copies a redacted diagnostic summary to the clipboard (it excludes secrets and the full log). This is the canonical way to attach diagnostics to an issue. The complete rotating log is available separately: GET /api/v2/log returns its last 64 KiB for local scripting, and GET /api/v2/diagnostic returns the same summary preview the button copies.
How to use it
- Reproduce the failure with the smallest local example (for example a single test ROM in a scratch folder).
- Capture the exact visible error and the log section around it. Look for:
- Import errors: which source, which manifest, what failed, and
Storefront scan timed out after 30s.for a store that exceeded its budget. - Launch failures: the validation error or the session's exit code, and emulator-setting warnings (
RetroArch settings could not be written,Plugin emulator settings). - Job failures: the job name and attempt (
openbox-job-*workers), including media queue items whoselast_errornames the provider failure. - Provider errors: IGDB/EmuMovies/Gameyfin messages (secrets redacted), and
The remote server returned an unsupported content typefor a bad download. apply_perfwarnings when a TDP limit was expected but not applied.- Startup errors: a library that failed to load or was restored from the last-known-good backup.
- Report with both the visible error and the copied log at OpenBoxGL issues. Security and credential problems belong in the Security and legal policy.
Related diagnostic files
<data-dir>/cache/launch_audit.jsonis the cached Launch Audit report read by the grid badges. The Python fallback also writes a rollinglaunch_audit.jsonlhistory (rotates to.1at 5 MiB); the Rust server does not.<data-dir>/media-queue.jsonis the durable media queue; failed items carrylast_errorand attempts.<data-dir>/storefront-status.json(or the status file reported byGET /api/v2/storefront/status) holds the last per-source scan state.
These are caches, not library state; removing them loses history, not games.
See also
- Interfaces and data, data directory layout and rotation
- Troubleshooting, the index of every troubleshooting area
- API local administrator,
GET /api/v2/log