Troubleshooting
SDK installation fails
- Confirm Python version ≥ 3.10
- Update pip with
pip install --upgrade pip - 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-levelcommsummary to locate where frames go missing:e2e_lostis network loss, whilesdk_droppedmeans your consumer is falling behind. For field definitions, see Wuji Hand 2 SDK reference — Hand2CommSummary
SDK version is incompatible with the firmware
- Check the SDK 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 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:
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_<serial>_<date>_<time>.jsonl. Exports created within the same second receive a numbered suffix instead of replacing an existing file.
When the device log ring is empty, frames is 0. The empty output file still indicates a successful export.
Handle Python export errors as follows:
WujiExceptionindicates that another export is using the device, the device or firmware doesn't support the current protocol, a connection or flash-log protocol error occurred, repeated retries couldn't complete, or the SDK couldn't create or write the output file.NodeOfflineErrorindicates that the target node went offline.
A failed export doesn't create an output file. For the C SDK call, status values, and result cleanup, see Wuji Hand 2 Flash Log Export.
Get technical support
When contacting support@wuji.tech, include the device logs, if available, along with the serial number, firmware version, SDK/CLI version, operating system and version, and reproduction steps related to the issue. Device log export varies by product. Start with Device Logging.