Troubleshooting

Run commands from any directory with the CLI installed. Keep public job/run IDs, timestamps, and error codes; remove tokens and sensitive input from reports.

Runtime does not become ready

mn --version
mn runtime status
mn runtime doctor
mn node list

Fix the named component or endpoint first. Start managed services with mn runtime start if they are stopped. Do not delete Redis or ~/.mn as an initial troubleshooting step.

A local folder is treated as a catalog ID

Use an explicit relative or absolute path:

mn blueprint validate ./my-blueprint
mn blueprint doctor ./my-blueprint

Replace ./my-blueprint with your package. Launch and doctor targets without ./, ../, or / are catalog IDs.

A blueprint fails validation or preparation

Read the named role document and error field. Current packages reference workflow, execution, contracts, and configuration documents from a small manifest. Use Author a blueprint for the format and dependency version syntax.

For model failures, inspect the model named by the diagnostic:

mn model list
mn model doctor <model-id>

Correct hardware, service, input, or version requirements before retrying. A force override can bypass checks and is not a routine repair.

A run is quiet or has failed

mn run show <run-id>
mn run logs <run-id> --channel events
mn run logs <run-id> --channel logs
mn run resources <run-id>
mn run human list <run-id> --pending

Look for waiting dependencies, human requests, resource admission, or a failed step. Docker workers can buffer output while a task runs; inspect deadlines and state before concluding that silence means failure. For finished work, collect outputs with mn run result <run-id>.

Ctrl+C from mn run watch detaches only. To stop unfinished work deliberately, use mn run cancel <run-id>; this cannot reverse external actions already performed.

Connected peers do not share one run

This is expected. One job executes on one owner node. Use Connect runtime nodes to inspect membership and owner eligibility. An unavailable owner can leave cached summaries readable while live control, logs, and artifacts fail; connecting another peer does not take over that run.

HTTP requests fail

For asynchronous requests, inspect the returned Operation until it completes or fails. Follow HTTP API for request examples and stream recovery.