# Troubleshooting Source: https://docs.ideharmony.com/troubleshooting First stop for anything not listed here: `harmony doctor` (add `--fix-safe` to repair the safe class of findings automatically). **Logs (typical locations):** | Platform | Logs | |---|---| | Windows | `%APPDATA%\NALA\logs\` (desktop app) and `%USERPROFILE%\.wmux\logs\` (background service) | | macOS | `~/Library/Logs/NALA/` (desktop app) and `~/.wmux/logs/` (background service) | | Linux | `~/.config/NALA/logs/` (desktop app) and `~/.wmux/logs/` (background service) | Topic index: [installation](/docs/troubleshooting/installation) · [providers](/docs/troubleshooting/providers) · [daemon](/docs/troubleshooting/daemon) · [session recovery](/docs/troubleshooting/session-recovery) · [website / web app](/docs/getting-started/web-app). ## Windows SmartScreen blocked the installer The preview build is unsigned, so SmartScreen may warn. Click **More info → Run anyway**. This is expected; verify the artifact against the published SHA-256 on [/download](/download) first. Do not disable SmartScreen globally. Full steps: [unsigned install guide](/download#first-open). ## macOS Gatekeeper blocked the app Gatekeeper may say the app is **damaged**. When the SHA-256 matches the download page, that means **unsigned**, not corrupt. Control-click → **Open**, then **Open** again. Fallback: `xattr -d com.apple.quarantine /Applications/NALA.app`. Do not disable Gatekeeper. Full steps: [unsigned install guide](/download#first-open). ## Voice dictation is not working Whisper needs Python 3.10+ on `PATH`. On first use Harmony offers to install `faster-whisper` for you; if that failed: ```powershell python --version # should print 3.10 or higher python -m pip install faster-whisper ``` Then retry dictation. Read Aloud needs no Python, just the one-time ~90 MB model download; if it failed, check the connection (first download only), check the logs, and restart Harmony to retry automatically. ## Linux AppImage will not run Install `libfuse2`: ```bash sudo apt install libfuse2 # Debian / Ubuntu sudo dnf install fuse-libs # Fedora / RHEL ``` Missing icons or menu entries mean `xdg-utils` is absent: `sudo apt install xdg-utils` (or `dnf` equivalent). ## `nala` or `wmux` not found after install Open a new terminal so the updated PATH is picked up. On Windows the shims live in `%LOCALAPPDATA%\NALA\bin\`; on Linux in `/usr/bin/` (packages) or `~/.local/bin/` (AppImage). Still missing? `harmony doctor --fix-safe` repairs shim registration. ## The app will not start after an update After three crashes within 60 seconds, Harmony enters safe mode automatically: minimal features, with a recovery screen offering retry, rollback, data export, reset, or logs. You can force it with the `--safe-mode` flag or a `safe-mode.flag` file in the user data directory. Rollback restores the previous binary (SHA-256 verified) once per update cycle. If a data migration failed, the pre-migration backup in `migration-backup-{timestamp}/` is retained for 7 days, and the migration resumes from its journal on next launch. ## Update check says "failed" The app keeps working from cached metadata and re-checks on next launch. "Update failed" means a network error or a checksum mismatch; the second is fail-closed by design, so retry on a different network before suspecting the build. ## Agents cannot message each other Check the A2A mode in the status bar: in **Off**, messages queue and nothing moves. Set it to Connect or Orchestrate. Also confirm both agents are in the same workspace, since discovery and messaging are workspace-scoped. ## The website or web app will not show live jobs Sign-in and Cloud status need a network. If you see Connection unavailable, reconnect and reload — private account pages are not kept offline, and commands are not queued on the device. Native store apps are not a current download. Full steps: [Use Harmony in a browser](/docs/getting-started/web-app). ## Getting help - Report bugs with logs attached: the [contact form](/contact-us) (the app repository and its issue tracker are private for now). - Ask the product itself: the Harmony Agent can run `harmony doctor` and read its own trace with `/trace`.