Troubleshooting
This guide describes the current build.
Get the useful log
- Open the tray menu.
- Open Developer → View Logs → Main Log.
- Reproduce the problem once.
- Copy only the relevant final lines from
%USERPROFILE%\.samsara\logs\samsara.log. Samsara keeps three older logs beside it (samsara.log.1to.3, 5 MB each).
Review a log before sending it. It can contain dictated text, application names, file paths, or provider errors.
Where things live
| What | Where |
|---|---|
| Everything of yours | %USERPROFILE%\.samsara\ (tray → Developer → Open Config Folder) |
| Settings | config.json in that folder. Close Samsara before editing it. |
| Automatic config backups | config_backups\, newest 15, plus last_known_good.json |
| Ava memory | ava_memory.md (readable; see Ava memory) |
| Snippets, aliases | snippets\snippets.jsonl, user_aliases.json |
| Speech models | The Hugging Face cache, %USERPROFILE%\.cache\huggingface\hub\, not the Samsara folder |
| Window layouts | %APPDATA%\Samsara\window_layouts.json |
“Samsara’s code changed on disk – restart to load it”
newer than v0.30.0-beta.2This appears only when you run Samsara from source. Every minute it checks whether a .py file changed; if so it shows a warning chip, adds a note to the tray tooltip and offers Restart Samsara above Exit. Packaged installs never show it. The check can be switched off with diagnostics.watch_code_changes. Samsara’s own tray menu is built so that Show Samsara, Settings, Something wrong? and Exit exist even if an optional section fails; a failed section appears as a disabled row, “… unavailable – see log”.
Report a problem
Open the tray item Something wrong? (it opens Settings → Help) and choose Get help:
- Create support bundle writes
samsara-report_YYYY-MM-DD_HH-MM.zipto your Desktop. It holds the last thousand lines of the log with private content redacted, a scrubbed copy of your settings, version information, and device names. Transcripts, memos, Ava memory and vault files are excluded. Nothing is uploaded; you attach it yourself. Redaction is automatic and best effort, so open the zip and look before you send it. - Copy safe diagnostics copies a short summary with no logs or secrets.
- Email the developer, Public GitHub report and Open live log are the other routes; see Support.
Saying “report a bug” or “send feedback” opens the matching GitHub form. It does not create the bundle.
What to send
Include the Samsara version, what you expected, what happened, and the smallest repeatable steps. For a visual problem, include a screenshot and your Windows display-scaling percentage. For microphone or wake problems, say which microphone and listening method you were using.
Microphone problems
- Check Windows microphone privacy settings; the first-run wizard says so if access is denied.
- In Settings → General → Microphone choose Refresh, or pick System default. The tray [MIC] menu switches device too. Refresh is refused while a recording is running.
- Run Tools → Mic Setup Guide from the tray, or Recalibrate Mic.
- If the device was unplugged, plug it back in. The audio engine retries every two seconds for a minute, then keeps checking every ten seconds, so a device that comes back reconnects without a restart.
- Restart Samsara as a last resort, then report it. (There is no “Reconnect microphone” tray item.)
Backups and restore
Settings → Help → Private backup / restore → Manage backup offers Export private configuration, Import private configuration and Restore automatic backup. An export contains everything in your configuration, including API keys, so never share it; it is not a support bundle. Importing keeps your current file as config.json.bak and offers a restart.
Updates
Update checks work only in a packaged install. They are off by default; turn on automatic checks to ask GitHub once a day, or use Settings → Help → Check for updates. Samsara only offers the latest stable release and never a newer beta; the download is SHA-256 verified. The build is not code-signed.
Windows SmartScreen
If Windows blocks the installer or app, use the steps in the SmartScreen section of the installation guide. Do not bypass a warning unless you intended to download Samsara from its official release.
CUDA
For CUDA problems, first switch back to CPU and confirm that Samsara starts. The optional pack needs its complete runtime set; see CUDA acceleration.