Troubleshooting¶

Device not found¶

Symptom: scan_devices returns no devices.

Possible causes:

USB not passed through (Docker): Use --privileged or --device flag.
```
docker run -i --rm --privileged sigrok-mcp-server
```
Missing firmware: Run check_firmware_status to verify. See the firmware guide.
Permission denied: On Linux, ensure your user is in the plugdev group, or use udev rules for the device.

Symptom: Commands fail with a timeout error.

Possible causes:

Slow device: Increase the timeout via environment variable:

docker run -i --rm -e SIGROK_TIMEOUT_SECONDS=120 sigrok-mcp-server

Serial timeout too short: For serial_query, increase timeout_ms (some instruments are slow to respond):
```
Tool: serial_query
Parameters:
  port: /dev/ttyUSB0
  command: "*IDN?"
  timeout_ms: 5000
```

Symptom: decode_protocol returns empty results.

Possible causes:

Wrong channel mapping: Ensure decoder channels match the capture channels. Use show_decoder_details to see required channels.
Wrong baud rate / protocol settings: Verify settings match the actual signal.
No transitions in data: The capture may not contain the expected signal activity.

Symptom: Server fails to start or tools return "sigrok-cli not found" errors.

Possible causes:

Not using Docker: The Docker image bundles sigrok-cli. If running from source, install it separately.
Custom path: Set SIGROK_CLI_PATH if sigrok-cli is installed in a non-standard location.

Symptom: serial_query returns a permission error.

Possible causes:

Docker: The serial device must be passed through:

docker run -i --rm --device=/dev/ttyUSB0 sigrok-mcp-server

Linux permissions: Add your user to the dialout group:
```
sudo usermod -a -G dialout $USER
```