pyro-mcp/docs/troubleshooting.md

Troubleshooting

pyro env pull or first-run install fails

Cause:

• the environment cache directory is not writable
• the configured registry artifact is unavailable
• the environment download was interrupted
• the host cannot reach registry-1.docker.io

Fix:

pyro env inspect debian:12
pyro env prune
pyro env pull debian:12

If you are validating a freshly published official environment, also verify that the corresponding Docker Hub repository is public.

pyro run --network fails before the guest starts

Cause:

• the host cannot create TAP devices or NAT rules

Fix:

pyro doctor

Then verify:

• ip
• nft or iptables
• /dev/net/tun
• host privilege for sudo -n

pyro doctor reports runtime issues

Cause:

• the embedded Firecracker runtime files are missing or corrupted

Fix:

• reinstall the package
• verify pyro doctor reports runtime_ok: true
• if you are working from a source checkout, ensure large runtime artifacts are present with git lfs pull

Ollama demo exits with tool-call failures

Cause:

• the model produced an invalid tool call or your Ollama model is not reliable enough for tool use

Fix:

pyro demo ollama -v

Inspect:

• model output
• requested tool calls
• tool results