On this page · jump to a step
Keep the state before taking action
Capture the project selector, readiness, permissions, active operation, pairing expiry and the server’s specific error. Preserve existing operation IDs and receipts so a retry does not erase context.
A locked Mac, disconnected session or client timeout does not by itself prove that a native operation was cancelled. Query the existing operation before deciding to retry.
Check in this order
| Symptom | What to inspect | Next step |
|---|---|---|
| Offline or paused | Mac availability, app, network and pause state | Restore local conditions, explicitly resume, then read status again. |
| Connected, not native-ready | Open Xcode project, native MCP permission and binding | Inspect the local failure and complete the required authorization. |
| Missing tools | Server catalog, client imports and local review state | Compare the actual catalogs; refresh through the client’s supported flow. |
| Permission denied | Read, edit, execution and Simulator scopes | Approve only the needed capability and check status again. |
| Device busy | Active operation and its ID | Query that operation instead of dispatching duplicate work. |
| A path, but no image | Output directory access, operation result and transfer errors | Confirm real image content before claiming visual verification. |
| Simulator unavailable | Original paired device, state, expiry and capabilities | Inspect the existing pairing first; renew locally if required. |
One healthy state is not the whole connection
Online status, native readiness, the correct project, tool availability, dispatch permission and Simulator pairing are separate facts. A success in one does not establish the others.
When the project or tools change
Closing the bound project tab, repurposing it for another project or updating Xcode with changed tool schemas may require a local review. Do not silently switch to another project to clear an error.
Collect useful diagnostics
- macOS, Xcode and Relayard versions.
- Time, target project and intended action.
- The exact error code and server-provided next action.
- Existing operation IDs, redacted logs and pairing expiry.
- Tools actually available in the client and the expected result that is missing.
Use the app’s diagnostic export when available. Remove tokens, verification codes, sensitive paths and business source before sharing.
Documentation updated: 2026-10-08