Troubleshooting

First stop for anything not listed here: nala doctor (add --fix-safe to repair the safe class of findings automatically), and the logs at %APPDATA%\wmux\logs\ (Windows) or ~/.config/wmux/logs/ (Linux/macOS).

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 if you want proof before running it. Do not disable SmartScreen globally.

macOS Gatekeeper blocked the app

System Settings → Privacy & Security → Open Anyway. Do not disable Gatekeeper. Note that some enterprise policies block unsigned software entirely; in that case, ask your admin or wait for the signed production release.

Voice dictation is not working

Whisper needs Python 3.10+ on PATH. On first use nala 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 nala 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, nala 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: GitHub Issues.
• Ask the product itself: the nala agent can run nala doctor and read its own trace with /trace.