Troubleshooting

Troubleshooting

This page lists the most common blumi problems and their fixes, grouped by area — installation, the always-on gateway, the blugo mobile app, the grid, GPU/accelerators, self-healing, and build/CI. blumi is a local-first, provider-agnostic AI coding agent that runs as one Rust binary on macOS and Linux (with an Android app, blugo), so most issues come down to PATH, network reachability, or host/accelerator configuration. Each entry below leads with the symptom in bold and the fix immediately after.

TL;DR / first things to check:

• blumi: command not found → add ~/.local/bin to your PATH.
• Gateway unreachable from your phone → you must install with --host <LAN-ip>, not loopback, and share the same Wi-Fi.
• Non-loopback bind rejects clients → it needs a password; run blumi serve pair.
• Grid peers don't appear → every node needs grid.enabled: true and the same grid.secret on the same LAN.
• Which accelerator is active? → run blumi accel doctor.
• Diagnostics to attach to any issue → blumi --version, your OS, and the relevant ~/.blumi/serve.log lines (redact secrets).

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

GPU / accelerators

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

Self-healing

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

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.

FAQ

Why do I get blumi: command not found after installing?

~/.local/bin isn't on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell rc (or set BLUMI_INSTALL_DIR to a directory already on PATH), then open a new shell.

Why can't my phone reach the blumi gateway?

Almost always because the gateway is bound to loopback. Reinstall the gateway with --host <LAN-ip> (not 127.0.0.1), confirm the phone and machine share the same Wi-Fi, and test from another device with curl http://<ip>:7777/api/health. A non-loopback bind also requires a password — run blumi serve pair.

Why don't my grid peers show up?

Every node must have grid.enabled: true and the exact same grid.secret, all on the same LAN with mDNS allowed. Verify with GET /api/grid/peers. If a node disappeared after you changed the secret, its grid_id changed — restart all nodes with the same secret, since identity is fixed at startup.

How do I tell which accelerator (CPU / CoreML / CUDA) blumi is using?

Run blumi accel doctor (also /accel in the TUI, or the Status tab in blugo). On Apple Silicon CoreML is on by default; elsewhere it's CPU unless you opted into CUDA with BLUMI_CUDA=1. Setting acceleration.mode = "cuda" on a CPU build degrades to CPU with a warning.

A CUDA build fails to load libonnxruntime.so — how do I fix it?

CUDA's ONNX Runtime is a shared library, and a plain cargo install copies only the binary. Re-run the current install.sh: the 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. If you don't need the in-process GPU embedder, use the lean build and run Ollama for GPU LLM and embeddings instead.

How do I turn off self-healing?

Set heal.enabled = false to disable recovery entirely, or heal.evolve = "off" to keep recovery and learning while stopping any self-modification. Inspect what it has done with /heal in the TUI or GET /api/heal. See Self-Management.

What should I include when reporting a blumi issue?

Open an issue with blumi --version, your OS, and the relevant ~/.blumi/serve.log lines (redact secrets). For accelerator problems, attach the output of blumi accel doctor.

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