thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/docs/troubleshooting.md
Thales Maciel 6e16e74fd5 Harden default environment pull behavior 
Fix the default one-shot install path so empty bundled profile directories no longer win over OCI-backed environment pulls or leave broken cached symlinks behind.

Treat cached installs as valid only when the manifest and boot artifacts are all present, repair invalid installs on the next pull, and add human-mode phase markers for env pull and run without changing JSON output.

Align the Python lifecycle example and public docs with the current exec_vm/vm_exec auto-clean semantics, and validate the slice with focused pytest coverage, make check, make dist-check, and a real default-path pull/inspect/run smoke.
2026-03-11 19:27:09 -03:00

1.9 KiB
Raw Blame History

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_RUNTIME_BUNDLE_DIR is a contributor override for validating a locally built runtime bundle. End-user pyro env pull should work without setting it.

pyro run fails closed before the command executes

Cause:

  • the bundled runtime cannot boot a guest
  • guest boot works but guest exec is unavailable
  • you are using a mock or shim runtime path that only supports host compatibility mode

Fix:

pyro doctor

If you intentionally want host execution for a one-off compatibility run, rerun with:

pyro run --allow-host-compat debian:12 -- git --version

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: PASS
  • or run pyro doctor --json and verify 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