# Troubleshooting

> Get from an unexpected error to a working inference pipeline.

## Start with doctor

```bash
cascadia doctor
```

It checks your environment and can detect the common case where OpenVINO sees only the CPU even though a GPU driver is installed.

## Inference is unexpectedly slow

Verify that your intended device is visible and selected. Check the engine and artifact format, then consult the [performance notes](https://github.com/labscommunity/cascadia/blob/main/docs/PERFORMANCE.md). First-time kernel compilation can be slower than subsequent starts.

## A downstream worker cannot be reached

Start the last stage first. Make sure its `--listen` address matches the upstream worker’s `--next` address and the host firewall permits that port. Workers wait for the downstream peer before timing out.

## The model directory is not found

`run` and `worker` require a local model directory, not a Hugging Face repo ID. Download and export through `cascadia shard`, or supply a whole-model OpenVINO IR directory for `ov-genai`.

## config.json is missing

Older shard exports may omit the model configuration. New `cascadia shard` exports include it. Re-export or copy the source model’s `config.json` into the expected artifact layout described in the [sharding reference](https://github.com/labscommunity/cascadia/blob/main/docs/SHARDING.md).

## Workers stop when SSH closes

Run workers under a service manager. Cascadia does not daemonize itself. See [Run as a background service](/guides/run-as-a-service/) for systemd, NSSM, and launchd recipes.

## Report an issue

Include your Cascadia version, hardware, selected engine, command, and relevant diagnostic output in a [GitHub issue](https://github.com/labscommunity/cascadia/issues). Remove private prompts and local secrets from logs before sharing them.