> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for common errors when running the iii engine and workers.

Solutions to errors you may hit while running the iii engine and workers.

## `KVM not accessible`

Workers boot inside a microVM that needs read/write access to `/dev/kvm`. On Linux hosts where your
user is not in the `kvm` group (common on WSL2), starting a worker fails with `KVM not accessible`.

Add your user to the `kvm` group:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
sudo usermod -aG kvm $USER
```

Then restart your session so the new group membership applies. On WSL2, run `wsl --shutdown` from a
Windows terminal and reopen your distribution.

> [!NOTE]
>
> For why workers run in microVMs, see [Engine](https://iii.dev/docs/0-25-0/understanding-iii/engine.md).

## An observer's target never runs

List the observers of the observed function:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii trigger engine::observers::list function_id=orders::create
```

Find yours by its `target` and read its `state`:

* `pending` or `error`: `reason` says why, for example the owner has not acknowledged it, the target
  is not registered, or the args were refused (`INVALID_ARGS`). See
  [Observer states](https://iii.dev/docs/0-25-0/using-iii/observers.md#observer-states).
* `active` with `fires` and `dropped` at 0: no event has reached it. Check `delivery`:
  * `owner`: the observer gets an event only when the function's code calls `obs.emit` or `obs.call`
    on it. Inside `onObserverAdded`, the observer is not active yet, so these calls do not deliver.
    See
    [Advanced function observation with owner delivery](https://iii.dev/docs/0-25-0/creating-workers/observable-functions.md#advanced-function-observation-with-owner-delivery).
  * `auto`: only invocations that start after the observer turned `active`, end with the outcome its
    `on` asks for (`success` by default), and pass its filters are events. A call already running
    when the observer turned `active` is not one, so call the function again.
* `dropped` or `activation_failures` above 0: events reached it and were dropped or failed, counted
  by reason (`OVERFLOW`, `LOOP_GUARD`, ...).

## `Logger` lines do not show up

`Logger` sends its lines to the engine. They do not appear in your worker's output. Look in the
engine's output (under `iii compose --up`, `.iii/compose/<namespace>/engine.log`), or run:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii trigger engine::logs::list
```

If they are not there either, the worker's OpenTelemetry export may be off (`OTEL_ENABLED=false`).
`Logger` then falls back to the language's own logging, which the Rust SDK prints only with a
`tracing` subscriber. See [Where the lines go](https://iii.dev/docs/0-25-0/creating-workers/observability.md#where-the-lines-go).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.