Log Files

Log Files

Emutastic writes a small set of diagnostic log files while it runs. They exist because most problems get reported from release builds where there's no debugger attached — a log file is often the only way to see what the app was doing when something went wrong. If you file a bug report, the relevant log from the table below is usually the most useful thing you can attach.

Every log is size-capped and rotates automatically — none of them can grow out of control. The cap is 2 MB per log (the main emulation logs get 5 MB). When a log hits its cap it is renamed to a single backup (.1, or .old.log) and a fresh file is started, so the worst case for any log is roughly double its cap on disk. The entire set together stays in the tens of megabytes.

All logs are safe to delete at any time. The app recreates them as needed.

Where they live

Everything is in ~/.local/share/Emutastic/Logs/ (in Portable Mode, PortableData/Logs next to the binary). One exception, kept where existing bug-report habits expect it:

• import_debug.log — in the data folder root (~/.local/share/Emutastic/)

The logs

File	What it records	Max size
emulator.log	Library-process activity around a game session: launch plumbing, session bring-up, teardown.	5 MB
emulator-host.log	Everything inside the game-host process: core loading, video/audio setup, controller polling, achievement activity, present-loop stats. The first log to check when a game won't launch, shows a black screen, or crashes. (Games run in a separate process on Linux — see [[Differences from Windows	Differences-from-Windows]].)
ra.log	RetroAchievements data traffic — API calls, cache activity, and parse failures for the Achievements tab, friends, and leaderboards.	2 MB
cloudsync.log	Cloud save sync activity — uploads, downloads, conflicts, and cleanup.	2 MB
cores.log	Core downloads and update checks — which URLs were fetched and whether they succeeded.	2 MB
screenscraper.log	Artwork and metadata lookups against ScreenScraper, including quota and login problems.	2 MB
import_debug.log	ROM import flow — console detection, archive extraction, and the artwork backfill after import.	2 MB
controller-diag.log	Controller detection and hot-plug events — which devices were found and what they identified as.	2 MB
recording_debug.log	Gameplay recording lifecycle — capture setup, encoding, and teardown.	2 MB
crash.log	Unhandled-exception details when something goes badly wrong.	2 MB
ui_freezes.log	One line whenever the UI thread stalls for half a second or more.	2 MB
startup_timings.log	How long each startup phase and navigation click took.	2 MB

(vulkan_debug.txt from the Windows app never appears on Linux — everything renders through OpenGL.)

Which ones are permanent and which are temporary

Long-term diagnostics — these stay. They cover the subsystems that talk to the outside world (cores, artwork, achievements, cloud sync) or depend heavily on your specific setup (controllers, imports, emulation itself):

emulator.log, emulator-host.log, ra.log, cloudsync.log, cores.log, screenscraper.log, import_debug.log, controller-diag.log, crash.log

Temporary instrumentation — these exist to hunt specific classes of bugs and will likely be removed (or disabled by default) as the app matures:

• ui_freezes.log and startup_timings.log watch for UI responsiveness problems.
• recording_debug.log covers the recording feature; it follows the same path once recording has been boring for a few releases.

Nothing in any log contains personal information — file paths on your own machine and your RetroAchievements username are the most identifying things that appear.