Troubleshooting
Resolve template errors, route responses, database status and Rust build problems in Miblo.
On this page
Run diagnostics
miblo doctor --project team-api
miblo db check --project team-apidoctor checks project metadata and prerequisites. db check tests the connection. Read Logs for the full error.
Unavailable template or 404
Check the version, source and access to template releases. Custom URLs need both the archive and its .sha256 sidecar.
The workspace lets you change source or retry while keeping the name, destination and port. A failed download does not create the project.
Template changed since project creation
The pinned local pack changed or is missing. Restore its exact content for models that depend on it. For future additions, select a published pack with u or:
miblo template update --project team-apiThis does not rewrite existing models or migration history. Do not delete metadata to bypass the check.
A route returns 501
The route uses Custom logic. Select it, press e, implement service.rs, then restart.
To reuse a model’s SQL directly, create a route with that model and a CRUD action: list, get, create, update or delete.
Orange or red database status
| Displayed status | Action |
|---|---|
| Database update required | Stop the API, then b → Apply migrations. |
| Database needs initialization | b → Initialize the database and tables. |
| Database unavailable | Check the connection; for MySQL, check the server and credentials. |
| Migration mismatch | Restore the applied migration, then write a new migration for the change. |
Conflicts or interrupted operations
Existing files, modified registries or incompatible code changes can stop generation. Resolve the reported files before retrying. Place manual route registration in src/lib.rs.
An interruption may leave .miblo/operation.lock and partial writes. Check that no operation is running, inspect the diff, restore a consistent state, then remove the stale lock. Multi-file writes are not an atomic transaction.
Language changes after restarting
Choose a language with Shift+L, then press Enter. If your shell defines MIBLO_LANGUAGE, it takes precedence at the next launch: unset it to use the saved choice.
If Miblo cannot save the preference, check the permissions of the preferences directory and the validity of settings.json. The current session remains usable.
Build failures, busy ports or missing commands
Install rustfmt with rustup component add rustfmt. For linker errors, check C/C++ tools. For an occupied port, change SERVER_PORT, refresh with F5 and restart.
Check Cargo’s PATH if the command is missing. Bug reports should include version, OS, command and error, without private .env content.