Skip to main content

​
A task stays pending or reports queue_wait_exceeded

  • Run phone_device_status and confirm the selected phone is online and not device-paused
  • A task can remain pending while another in-app agent or chat task is using the phone’s execution lane
  • Increase queue_wait_timeout_s when the phone legitimately needs more time to become available; the maximum is 300 seconds
  • If the task reached queue_wait_exceeded, start a new task after the phone becomes available

​
A task stays paused

  • Call phone_task_monitor and confirm the task reports status: "paused"
  • Call phone_task_resume with the same session_id and task_id
  • Continue monitoring the original task_id; resume does not create a replacement task
  • Optionally include a short instruction if the agent should change course after resuming

​
The monitor returns before the task is finished

  • status: "paused" is actionable; resume the same task and monitor its original task_id
  • monitor_timed_out: true is not a task failure; call phone_task_monitor again
  • A completed needs_user_control result requires user input and a continuation task - see below
  • Use phone_task_status only for a point-in-time snapshot, not a polling loop

​
The phone asks for user input

  • message_user, confirmation, login, login-details, and CAPTCHA actions complete with terminal: "needs_user_control"
  • Inspect error.control_type and error.prompt to determine what the phone needs
  • Send the user’s answer with phone_task_message using the completed task’s session_id and task_id
  • Monitor the returned continuation_task_id; the completed original task will not become running again
  • Repeating the same answer is safe, but a different second answer is rejected

​
My task was cancelled and I didn’t cancel it

terminal: "stopped_by_user" has three sources: phone_task_cancel, phone_session_end, and displacement - starting a new phone_run_task on the same device cancels its existing pending, running, or paused MCP task. Serialize work per device, or use separate devices for parallel workflows.

​
session_not_found_or_inactive

  • Start a new session with phone_session_start (or just call phone_run_task, which creates one)
  • Make sure subsequent task calls use the latest active session
  • Avoid reusing a session after calling phone_session_end
  • Sessions expire - check expires_at on long workflows
  • If a client caches old tool state, reconnect the MCP server and try again

​
task_not_found

  • Use the exact task_id returned by phone_run_task; do not construct or reuse IDs across sessions
  • After answering a needs_user_control task, monitor the returned continuation_task_id, not the original completed task
  • Tasks expire; if the correct ID no longer resolves, start a replacement task with phone_run_task

​
A mobile log shows /mcp-result returning 404

  • This only appears if you are reading the Android app’s own device logs; MCP clients never see this endpoint
  • The 404 is harmless: the phone reported a result for a request that had already timed out or been superseded, so the server discarded it
  • If your original tool call timed out without a result, retry that tool call; there is nothing to fix on the phone

​
Other terminal outcomes

Every completed task carries a terminal; the terminal outcomes table covers all nine, and Error handling gives the recovery move for each.