---
{
  "id": "platform.local.errors-and-debugging",
  "topic": "local",
  "title": "Local Desktop Bridge errors and debugging",
  "locale": "en",
  "version": "2026-08-23",
  "summary": "Local failures should be diagnosed in connection, capability, path, execution, then infrastructure order, with retry behavior based on the typed result.",
  "content": "Debug local actions in gate order. First resolve connection for `LOCAL_DESKTOP_NOT_CONNECTED`. Then inspect capability: `LOCAL_CAPABILITY_UNAVAILABLE` is missing live runtime support, `LOCAL_CAPABILITY_NOT_GRANTED` is a device/Agent authorization mismatch, and `LOCAL_CAPABILITY_CHECK_FAILED` is a temporary check failure. Next resolve `LOCAL_FS_ROOT_DENIED` without guessing or widening a root. Then handle execution failures such as `DESKTOP_TOOL_TIMEOUT` or `DESKTOP_TOOL_CANCELLED`, and finally `DESKTOP_ROUTING_UNAVAILABLE`.\n\nEvery action has a registry deadline. On timeout the server sends a kill and treats the action as failed; never claim it completed. Availability failures can be retried only after connection or authorization is fixed. After a timeout or cancellation, tell the user the observed status and confirm the desktop's real state before deciding whether another attempt is safe. Platform routing unavailability is temporary, so a later retry is reasonable.\n\nPlatform audit records action identity, argument key names and serialized byte count, status/error metadata, and an optional desktop audit ID. It does not record argument values, local paths, command text, clipboard text, screenshots, or tool results; the desktop keeps its own activity record. The current action result, status, and typed error always override catalog prose.\n",
  "aliases": [
    "local tool failed",
    "desktop timeout",
    "capability denied",
    "filesystem path denied",
    "desktop routing unavailable",
    "action cancelled"
  ],
  "tags": [
    "local",
    "errors",
    "debugging",
    "audit"
  ],
  "relatedActions": [],
  "relatedActionPrefixes": [
    "arinova.local."
  ],
  "url": "https://docs.arinova.ai/en/kb/local/errors-and-debugging/"
}
---

Debug local actions in gate order. First resolve connection for `LOCAL_DESKTOP_NOT_CONNECTED`. Then inspect capability: `LOCAL_CAPABILITY_UNAVAILABLE` is missing live runtime support, `LOCAL_CAPABILITY_NOT_GRANTED` is a device/Agent authorization mismatch, and `LOCAL_CAPABILITY_CHECK_FAILED` is a temporary check failure. Next resolve `LOCAL_FS_ROOT_DENIED` without guessing or widening a root. Then handle execution failures such as `DESKTOP_TOOL_TIMEOUT` or `DESKTOP_TOOL_CANCELLED`, and finally `DESKTOP_ROUTING_UNAVAILABLE`.

Every action has a registry deadline. On timeout the server sends a kill and treats the action as failed; never claim it completed. Availability failures can be retried only after connection or authorization is fixed. After a timeout or cancellation, tell the user the observed status and confirm the desktop's real state before deciding whether another attempt is safe. Platform routing unavailability is temporary, so a later retry is reasonable.

Platform audit records action identity, argument key names and serialized byte count, status/error metadata, and an optional desktop audit ID. It does not record argument values, local paths, command text, clipboard text, screenshots, or tool results; the desktop keeps its own activity record. The current action result, status, and typed error always override catalog prose.