• 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.

• 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).

• 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.

• 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).

• A Linux build froze / OOM'd the machine. Older builds release-linked the heavy ONNX embedder by default. It's now Apple-default + opt-in elsewhere, so a plain Linux install is lean (FTS5) and doesn't do that multi-GB native link. Only BLUMI_CUDA=1 / --features gpu-cuda pulls it in.
• error while loading shared libraries: libonnxruntime.so (CUDA build). CUDA's ONNX Runtime is a shared lib; a plain cargo install copies only the binary. The installer's BLUMI_CUDA=1 path ships the .so next to the binary, verifies blumi --version loads, and auto-falls back to a lean build if it can't. Re-run the current install.sh; if you don't need the in-process GPU embedder, use the lean build and run Ollama for GPU LLM + embeddings instead.
• CUDA build error: "When using download-binaries, a TLS feature must be configured." A non---locked resolve floated ort-sys to a broken release. blumi pins ort-sys = =2.0.0-rc.9 and the installer uses --locked on the CUDA path — reinstall with the current install.sh.
• Which accelerator is active? blumi accel doctor (also /accel in the TUI, the Status tab in blugo). On Apple Silicon CoreML is on by default; elsewhere it's CPU unless you opted into CUDA. Setting acceleration.mode = "cuda" on a CPU build degrades to CPU with a warning. See Memory & Knowledge → GPU acceleration.

• Turn it off. heal.enabled = false disables recovery entirely; heal.evolve = "off" keeps recovery + learning but stops any self-modification. See Self-Management.
• Inspect it. /heal in the TUI or GET /api/heal on the gateway shows recent recoveries, learned fixes, and evolution proposals.
• A fix didn't get reused. Learned fixes are agent-namespace memories — recall + diffusion need the same prerequisites as any memory (embeddings or FTS5 fallback; grid up for cross-node sharing).

• 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).