Troubleshooting

Recover from the reported state, without blindly replaying device input.

Common problems

Missing CLI

iphone-use: command not found

Check installation and the client’s PATH; restart the client. A plugin does not include the executable.

Missing skill

Plugin installed, skill missing

Enable the plugin, use its namespaced invocation and start a new session. Refresh both marketplace and installed plugin when updating.

Setup required

setup_required / setup_update_required

Only in Runner mode, run the indicated setup command with the release CLI, then connect again.

Signing mismatch

profile_not_found / signing mismatch

Check the profile, certificate and private key, device, team and bundle ID. Pass the matching signing options.

CoreDevice timeout

coredevice_initialization_timeout

Compare one read-only devices call in an approved local host context. A sandbox timeout does not prove that the phone is disconnected. Do not disable the sandbox globally or repeatedly reset services.

Device trust

Locked phone / trust incomplete

Unlock the iPhone and complete trust and Developer Mode dialogs before reconnecting.

Changed screen

screen_changed / not_dispatched

Read the error and requiresObservation. Acquire fresh references when requested; do not increase thresholds just to bypass the rejection.

Uncertain input

unknown

Input may have happened. Observe and read the PNG before choosing the next action.

Observation failed

Action succeeded, observation failed

Preserve action.outcome and recover with observe. Repeating input does not repair a screenshot read.

native_media_busy

End Device Hub or the other client’s control session, then follow the returned recovery and observe again. Do not stop foreign sessions or replay unknown input.

Client errors before device control

If the client cannot read its configuration, fix that mismatch first without replacing the full configuration with a sample. A selected model requiring a newer client is also a client-version issue: update through the client’s installation method or select a supported model.

Report a reproducible issue

Ask the agent to disconnect its session if possible. Record the command, error, what was verified and what remains uncertain. Include client, CLI, Xcode, macOS and iOS versions.

Keep device identifiers, private screenshots, logs and provisioning profiles out of public reports. Then open an issue on GitHub.