90 lines
1.7 KiB
Markdown
90 lines
1.7 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 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_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
|