Thales Maciel
6e16e74fd5
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.
94 lines
1.9 KiB
Markdown
94 lines
1.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pyro doctor
|
|
```
|
|
|
|
If you intentionally want host execution for a one-off compatibility run, rerun with:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pyro demo ollama -v
|
|
```
|
|
|
|
Inspect:
|
|
|
|
- model output
|
|
- requested tool calls
|
|
- tool results
|