> ## 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. # 故障排查 ## SDK 安装失败 1. 确认 Python 版本 ≥ 3.10 2. 使用 `pip install --upgrade pip` 更新 pip 3. 遇到编译错误时，尝试安装预编译的 wheel 包 ## 脚本运行中抛出异常 | 异常消息 | 原因 | 处理 | | - | - | - | | `DeviceNotFound` | 设备未发现 | 检查物理连接和网络 | | `Disconnected` | 连接中断 | 检查线缆，重新连接 | | `ConnectionTimeout` | 连接超时 | 检查网络连接或增加 timeout\_ms 参数 | | `OperationTimeout` | 操作超时 | 增加 timeout\_ms 参数或检查设备状态 | | `StreamClosed` | 订阅流关闭 | 设备可能断开，重新连接 | | `SessionAlreadyExists` | 同一设备已建立会话 | 沿用既有句柄，或先 `disconnect()` 后重连 | | 连接 Wuji Hand 报错并列出未响应的关节 | 手未就绪，部分关节没有应答 | 检查供电与线缆，确认关节上电后重连。Python SDK 与 C SDK 表现一致 | | `WujiException` | Wuji Hand 2 写入 `hand.mit_params()`（`kp` / `kd` 均要求非负）、`hand.effort_limit()`（非负）或 `joint_command` 实时指令时传入 NaN / Inf / 负值 | 在写入前过滤非法值 | | `WujiException` | Wuji Hand 2 写入 `hand.effort_limit()` 的值超出设备当前允许上限，设备拒绝该次写入 | 调低写入值。上限由固件设定，读回 `effort_limit` 确认当前生效值 | | `WujiException` | 向 Wuji Hand 2 的 `hand.joint(index)` 传入超出 `0..=19` 范围的索引 | 传入 0 到 19 的整数。SDK 会在创建关节句柄前抛出 `WujiException` | ## 订阅数据延迟或丢帧 * 检查网络带宽和延迟（有线连接优于 WiFi） * 减少同时订阅的数据流数量 * 确认回调函数中没有耗时操作阻塞接收 * Wuji Hand 2 可订阅 `hand.joint_diagnostics()`，其帧级 `comm` 摘要能定位丢帧发生在哪一段：`e2e_lost` 是网络丢帧，`sdk_dropped` 是消费端处理不及时。字段定义见 [Wuji Hand 2 SDK 接口参考 — Hand2CommSummary](/docs/wuji-hand/latest/sdk-reference/diagnostics/#hand2commsummary) ## SDK 版本与固件版本不兼容 * 查看 [SDK 版本发布记录](/release-notes) 了解版本对应关系 * 建议 SDK 和固件保持同一主次版本（如均为 0.6.x） ## 升级 SDK 后 `tactile_binary` 或 `tactile_residual` 不发数据 Wuji Glove 触觉数据布局调整为 24×31（原 24×32）。SDK 按新布局校验入帧尺寸与接触标定模型，二者任一仍为 24×32 即停发对应数据流，避免错位输出。恢复路径：将 Wuji Glove 固件升级至支持 24×31 的版本，并按新布局重做触觉接触标定。详见 [Wuji Glove 触觉数据 reference](/docs/wuji-glove/sdk-data-reference/tactile)。 ## 设备日志导出 ### Flash 日志导出 Wuji SDK v2026.8.31 提供 Wuji Hand 2 Flash 历史日志导出接口。调用 `export_flash_logs()` 后，当前线程会一直等待，直到设备日志读取完成并写入文件，函数才会返回包含 `path` 和 `frames` 的字典。导出文件采用 JSONL 格式，每行是一条 JSON 记录。Wuji Hand 2 固件 v2.6.0 及以上支持同一设备的并发导出，较早固件请依次导出。对于不支持 Flash 日志的固件或协议版本，导出会提示不支持： ```python theme={null} result = hand.export_flash_logs() print(result["path"], result["frames"]) ``` `path` 是导出文件路径，`frames` 是成功解码的日志帧数。向 `out_dir` 传入目录路径可指定保存位置。未传入时，文件保存到 `~/.wuji/logs/flash___