nodes/troubleshooting.md
當節點在狀態中可見但節點工具失敗時，請使用此頁。指令階梯
- 節點已連線，且已為角色
node完成配對。 nodes describe包含你正在呼叫的能力。- Exec approvals show expected mode/allowlist.
前景需求
canvas.*、camera.* 與 screen.* 在 iOS／Android 節點上僅能於前景使用。
快速檢查與修正：
NODE_BACKGROUND_UNAVAILABLE，請將節點 App 切換到前景後再試一次。
權限矩陣
Pairing versus approvals
這是不同的關卡：- 裝置配對：此節點是否能連線至 Gateway 閘道器？
- Exec 核准：此節點是否能執行特定的 Shell 指令？
system.run 失敗，請修正 exec 核准／允許清單。
常見節點錯誤代碼
NODE_BACKGROUND_UNAVAILABLE→ App 在背景；請切換到前景。CAMERA_DISABLED→ 節點設定中停用了相機切換。*_PERMISSION_REQUIRED→ 缺少／被拒絕的 OS 權限。LOCATION_DISABLED→ 位置模式已關閉。LOCATION_PERMISSION_REQUIRED→ 未授與請求的位置模式。LOCATION_BACKGROUND_UNAVAILABLE→ App 在背景，但僅有「使用期間」權限。SYSTEM_RUN_DENIED: approval required→ Exec 請求需要明確核准。SYSTEM_RUN_DENIED: allowlist miss→ 指令被允許清單模式阻擋。
快速復原流程
- 重新核准裝置配對。
- Re-open node app (foreground).
- 重新授與 OS 權限。
- 重新建立／調整 exec 核准政策。