Troubleshooting
Common issues and direct fixes
Run baseline diagnosis first, then use the matrix below to identify the likely fix path.
Baseline diagnosis
mosaic --project-state status
mosaic --project-state health
mosaic --project-state doctor
mosaic --project-state logs --tail 80Issue matrix
| Symptom | Check | Typical fix |
|---|---|---|
models list returns 404 |
mosaic configure --show |
Fix base URL, avoid duplicated /v1 on Azure endpoint |
command not found: mosaic |
which mosaic |
Add Cargo bin to PATH and restart shell |
| Auth or network error | mosaic health + env vars |
Verify key env name/value and endpoint reachability |
channels and gateway checks
mosaic --project-state channels list
mosaic --project-state channels logs --channel all --tail 50
mosaic --project-state gateway probe