Troubleshooting

Troubleshooting

Install / run

• blumi: command not found — ~/.local/bin isn't on PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell rc, or set BLUMI_INSTALL_DIR.
• Source build fails — install Rust (https://rustup.rs); the source path needs cargo.
• No provider configured — run blumi login. See Configuration.

Gateway (blumi serve)

• serve status says not running — blumi serve start; check ~/.blumi/serve.log.
• Phone can't reach it — confirm you installed with --host <LAN-ip> (not loopback) and that phone + machine share the same Wi-Fi. Test from another device: curl http://<ip>:7777/api/health.
• "password required" — a non-loopback bind must have a password. Run blumi serve pair.
• Linux: service doesn't start before login — loginctl enable-linger $USER.
• macOS: "Unload failed" during install — harmless (it pre-unloads a non-existent agent).

Mobile app (blugo)

• Gateway not discovered — add it by IP (host:port) instead; ensure serve status is running and you're on the same LAN. (Android needs multicast permission, which the app declares.)
• Login fails — re-check the password from blumi serve pair.
• Stale view — pull-to-refresh on the chat; cached tabs revalidate automatically.
• Voice key won't "stick" — keys are write-only; the app shows saved ✓ and never returns them. Re-enter the key to re-authenticate / reload the voice dropdown. See Voice.

Grid

• Peers don't appear — every node needs grid.enabled: true and the same grid.secret; all must be on the same LAN with mDNS allowed. Verify with GET /api/grid/peers. See Grid.
• A node vanished after changing the secret — its grid_id changed; restart all nodes with the same secret (identity is set at startup).

Build / CI

• CI red on cargo fmt — run cargo fmt --all and commit.
• Clippy passes locally but fails in CI — CI runs on Linux; macOS-only code must be #[cfg(target_os = "macos")]-guarded or it trips dead_code under -D warnings.
• A TUI test flakes — tests that set the process-global icon mode must be serialized (a shared Mutex), since cargo runs tests in parallel.

Still stuck? Open an issue with blumi --version, your OS, and the relevant ~/.blumi/serve.log lines (redact secrets).