Troubleshooting

Start with doctor

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. 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.

Workers stop when SSH closes

Run workers under a service manager. Cascadia does not daemonize itself. See Run as a background 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. Remove private prompts and local secrets from logs before sharing them.