> ## Documentation Index > Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting ## SDK installation fails 1. Confirm Python version ≥ 3.10 2. Update pip with `pip install --upgrade pip` 3. If you encounter compilation errors, try installing the pre-built wheel package ## Script throws an exception during execution | Exception Message | Cause | Resolution | | - | - | - | | `DeviceNotFound` | Device not discovered | Check physical connection and network | | `Disconnected` | Connection interrupted | Check cables, reconnect | | `ConnectionTimeout` | Connection timed out | Check network connection or increase timeout\_ms parameter | | `OperationTimeout` | Operation timed out | Increase timeout\_ms parameter or check device status | | `StreamClosed` | Subscription stream closed | Device may have disconnected, reconnect | | `SessionAlreadyExists` | A session for the same device already exists | Keep using the existing handle, or `disconnect()` and reconnect | | Connecting to a Wuji Hand fails and names unresponsive joints | The hand isn't ready and some joints didn't answer | Check power and cabling, then reconnect once the joints are powered. The Python SDK and C SDK behave the same | | `WujiException` | Wuji Hand 2 write to `hand.mit_params()` (`kp` / `kd` both required non-negative), `hand.effort_limit()` (non-negative), or `joint_command` realtime publisher receives NaN / infinity / negative values | Filter invalid values before writing | | `WujiException` | Wuji Hand 2 write to `hand.effort_limit()` exceeds the ceiling the device currently allows, so the device rejects the write | Lower the value. Firmware sets the ceiling — read `effort_limit` back to confirm what's in effect | | `WujiException` | Calling Wuji Hand 2 `hand.joint(index)` with an index outside `0..=19` | Pass an integer from 0 through 19. The SDK raises `WujiException` before creating a joint handle | ## Data subscription has latency or frame drops * Check network bandwidth and latency (wired connection preferred over WiFi) * Reduce the number of simultaneously subscribed data streams * Ensure callback functions don't contain blocking operations * On Wuji Hand 2, subscribe to `hand.joint_diagnostics()` and read the frame-level `comm` summary to locate where frames go missing: `e2e_lost` is network loss, while `sdk_dropped` means your consumer is falling behind. For field definitions, see [Wuji Hand 2 SDK reference — Hand2CommSummary](/en/docs/wuji-hand/latest/sdk-reference/diagnostics/#hand2commsummary) ## SDK version is incompatible with the firmware * Check the [SDK release notes](/en/release-notes) for version compatibility * Keep SDK and firmware on the same minor version (e.g., both 0.6.x) ## After upgrading the SDK, `tactile_binary` or `tactile_residual` stops producing data The Wuji Glove tactile data layout now uses 24×31 (was 24×32). The SDK validates incoming frame size and the loaded contact calibration model against the new layout — if either still targets 24×32, the affected streams stop publishing to prevent misaligned output. To recover, upgrade the Wuji Glove firmware to a version that supports 24×31 and re-run tactile contact calibration under the new layout. See the [Wuji Glove tactile data reference](/en/docs/wuji-glove/sdk-data-reference/tactile) for details. ## Device Log Export ### Flash Log Export Wuji SDK v2026.8.31 provides the Wuji Hand 2 Flash log export API. After calling `export_flash_logs()`, the current thread waits until the SDK reads the device logs and writes the output file before the function returns a dictionary with `path` and `frames`. The output file uses JSONL format, with one JSON record per line. Wuji Hand 2 firmware v2.6.0 and later supports concurrent exports from the same device. Export logs one at a time with earlier firmware. For firmware or protocol versions that don't support Flash logs, the export reports that it isn't supported: ```python theme={null} result = hand.export_flash_logs() print(result["path"], result["frames"]) ``` `path` is the output file path, and `frames` is the number of successfully decoded log frames. Pass a directory to `out_dir` to choose the destination. Without `out_dir`, the SDK writes to `~/.wuji/logs/flash___