# Troubleshooting

## Validation failures before startup

If `shmpipeline validate` fails, the most common causes are:

- duplicate shared-memory names
- duplicate kernel names
- kernels referencing undefined streams
- invalid storage combinations between streams and kernel kinds
- multiple kernels producing the same output stream

Use `shmpipeline describe pipeline.yaml` to confirm the intended graph shape.

## Worker stays in `waiting-input`

This means the worker process is alive but has not yet received its first trigger input.

Typical causes:

- no external producer is writing the source stream
- the wrong stream is being driven
- a synthetic input writer was not started for a source stream

## Worker becomes `idle`

This means the worker has processed frames before but has not made recent output progress.

Typical causes:

- upstream input has stalled
- the configured timeout is too aggressive for the workload
- a long-running stage is introducing backpressure

## GPU viewer or CPU reader cannot inspect a stream

If a GPU stream must be readable from CPU code, create it with `cpu_mirror: true`.

## GPU runtime requirements

GPU support depends on a compatible CUDA and PyTorch environment. When CUDA is unavailable, GPU-specific tests are skipped and GPU examples will not run.

## Repeated lifecycle testing

For release testing or stress testing, repeatedly exercise:

- `build()`
- `start()`
- `stop()`
- `shutdown()`

This catches stale-handle, teardown, and resource ownership issues earlier than single-run smoke tests.