Troubleshooting

First stop for anything not listed here: nala doctor (add --fix-safe to repair the safe class of findings automatically).

Logs (typical locations):

Topic index: installation · providers · daemon · session recovery.

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 first. Do not disable SmartScreen globally. Full steps: unsigned install guide.

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.

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:

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:

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? nala 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.

Getting help

• Report bugs with logs attached: the contact form (the app repository and its issue tracker are private for now).
• Ask the product itself: the nala agent can run nala doctor and read its own trace with /trace.