Node troubleshooting

Use this page when a node is visible in status but node tools fail.

Command ladder

remoteclaw status
remoteclaw gateway status
remoteclaw logs --follow
remoteclaw doctor
remoteclaw channels status --probe

Then run node-specific checks:

remoteclaw nodes status
remoteclaw nodes describe --node <idOrNameOrIp>
remoteclaw approvals get --node <idOrNameOrIp>

Healthy signals:

Node is connected and paired for role node.
nodes describe includes the capability you’re calling.
Exec approvals show the expected mode/allowlist.

Foreground requirements

canvas.*, camera.*, and screen.* are foreground-only on iOS/Android nodes.

Quick check and fix:

remoteclaw nodes describe --node <idOrNameOrIp>
remoteclaw nodes canvas snapshot --node <idOrNameOrIp>
remoteclaw logs --follow

If you see NODE_BACKGROUND_UNAVAILABLE, bring the node app to the foreground and retry.

Permissions matrix

Capability	iOS	Android	macOS node app	Typical failure code
`camera.snap`, `camera.clip`	Camera (+ mic for clip audio)	Camera (+ mic for clip audio)	Camera (+ mic for clip audio)	`*_PERMISSION_REQUIRED`
`screen.record`	Screen Recording (+ mic optional)	Screen capture prompt (+ mic optional)	Screen Recording	`*_PERMISSION_REQUIRED`
`location.get`	While Using or Always (depends on mode)	Foreground/Background location based on mode	Location permission	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (node host path)	n/a (node host path)	Exec approvals required	`SYSTEM_RUN_DENIED`

Pairing versus approvals

Three separate gates control whether a node command succeeds:

Device pairing: can this node connect to the gateway?
Gateway node command policy: is the RPC command ID allowed by gateway.nodes.allowCommands / denyCommands and platform defaults?
Exec approvals: can this node run a specific shell command locally?

Node pairing is an identity/trust gate, not a per-command approval surface. For system.run, the per-node policy lives in that node’s exec approvals file (remoteclaw approvals get --node ...), not in the gateway pairing record.

Quick checks:

remoteclaw devices list
remoteclaw nodes status
remoteclaw approvals get --node <idOrNameOrIp>
remoteclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

Pairing missing: approve the node device first.
nodes describe missing a command: check the gateway node command policy and whether the node actually declared that command on connect.
Pairing fine but system.run fails: fix exec approvals/allowlist on that node.

For approval-backed host=node runs, the gateway also binds execution to the prepared canonical systemRunPlan. If a later caller mutates the command, cwd, or session metadata before the approved run is forwarded, the gateway rejects the run as an approval mismatch instead of trusting the edited payload.

Common node error codes

Code	Meaning
`NODE_BACKGROUND_UNAVAILABLE`	App is backgrounded; bring it to the foreground.
`CAMERA_DISABLED`	Camera toggle disabled in node settings.
`*_PERMISSION_REQUIRED`	OS permission missing/denied.
`LOCATION_DISABLED`	Location mode is off.
`LOCATION_PERMISSION_REQUIRED`	Requested location mode not granted.
`LOCATION_BACKGROUND_UNAVAILABLE`	App is backgrounded but only While Using permission exists.
`SYSTEM_RUN_DENIED: approval required`	Exec request needs explicit approval.
`SYSTEM_RUN_DENIED: allowlist miss`	Command blocked by allowlist mode. On Windows node hosts, shell-wrapper forms like `cmd.exe /c ...` are treated as allowlist misses in allowlist mode unless approved via the ask flow.

Fast recovery loop

remoteclaw nodes status
remoteclaw nodes describe --node <idOrNameOrIp>
remoteclaw approvals get --node <idOrNameOrIp>
remoteclaw logs --follow

If still stuck:

Re-approve device pairing.
Re-open the node app (foreground).
Re-grant OS permissions.
Recreate/adjust the exec approval policy.