# 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