Troubleshooting
When something is stuck, and what to send when it broke.
Log times and crash times differ
Daily log filenames use local time and crash artifacts use UTC, so line them up with the offset in mind before concluding they are unrelated.
Nothing is happening
A message that produces no response and no spinner usually means the CLI underneath is waiting on a confirmation prompt in its terminal. Answer it there and the chat resumes.
After a crash
Three kinds of diagnostic file may be on disk, all local, none uploaded on their own. Send them with a bug report from Getting help when you want them looked at.
Reporting a crash
If PandaOS quits unexpectedly, three kinds of diagnostic artifacts may be on disk. All are local-only, nothing is uploaded automatically.
Daily log filenames use local time; crash artifact filenames use UTC. When correlating the two, be aware of the timezone offset (e.g. a crash at 23:30 local time on Apr 20 produces
main-20260420.logandcrash-20260421T...-*.jsonside by side).
Daily log file
The main process mirrors its logs to a daily file for the last 7 days. Attach the file for the day of the crash.
- macOS:
~/Library/Logs/PandaOS/main-YYYYMMDD.log - Windows:
%APPDATA%\PandaOS\logs\main-YYYYMMDD.log - Linux:
~/.config/PandaOS/logs/main-YYYYMMDD.log
Each file contains plain-text log lines prefixed by level and tag. Lifecycle markers ([lifecycle] {"kind":"startup", ...} and [lifecycle] {"kind":"clean-exit", ...}) make it possible to tell whether the previous session exited cleanly. A missing clean-exit marker before the next startup marker means the previous run crashed.
Crash artifacts
When the JS side of the main process throws an uncaught error, rejects an unhandled promise, or a renderer / child process dies, a structured JSON file is written alongside the daily log:
crash-YYYYMMDDTHHMMSS-<kind>.jsonwhere <kind> is one of uncaughtException, unhandledRejection, render-process-gone, or child-process-gone. Each file contains the error, stack trace, app / Electron / Node versions, memory snapshot, and the last 200 log entries leading up to the crash.
Native minidumps (rare)
For native-side aborts (SIGSEGV, V8 FATAL), Electron writes a minidump to a separate directory. These are binary files, attach them as-is if you can find them; they're only useful to developers.
- macOS:
~/Library/Application Support/PandaOS/Crashpad/completed/ - Windows:
%APPDATA%\PandaOS\Crashpad\reports\ - Linux:
~/.config/PandaOS/Crashpad/completed/
What to send
When filing a bug, a GitHub issue, or a support email: attach the daily log for the day of the crash and any crash-*.json files written around the time of the crash. The /api/crashes endpoint (reachable by the renderer when the bridge server is up) also lists all crash artifacts with their paths for convenience.