Troubleshooting
Run remotxai doctor on the computer first. Every line should say PASS. A FAIL line names the problem.
The app is stuck
Section titled “The app is stuck”Settings → Appearance → Reload app reloads the screen. Sessions keep running. If it’s still stuck, check the service on the computer and start it if it’s down:
remotxai statusremotxai service startThe app cannot reach my computer
Section titled “The app cannot reach my computer”The app says Computer unreachable, Offline or Asleep.
- Wake the computer and check its network.
- Run
remotxai statuson the computer. If the service isn’t running, start it. - Check its
relay linkline.linked to wss://app.remotxai.com with organisation admissionmeans the app can reach the computer.refused:gives the reason, for examplehost-not-endorsed.off:says why it isn’t connecting at all.remotxai doctorshows the same in itsrelay configrow. - If you ran
remotxai down, runremotxai up. - If
relay linked nowsaysnoandrelay last linkedis minutes old, runremotxai reload --relay. It drops the relay connection and dials again without restarting the service. Run it once; a second call within 2 seconds answerstry again in N s. - In the app, tap Reconnect.
remotxai statusremotxai service statusremotxai service startremotxai upremotxai reload --relaySessions keep running while the link is down. The app catches up when it returns. Don’t resend a prompt while it reconnects.
The connection drops after sleep or a network change
Section titled “The connection drops after sleep or a network change”The app shows “Connection dropped, reconnecting (sessions keep running)”. Keep it open. The computer reconnects by itself and logs relay linked: when it does:
remotxai logs -n 100A sleeping computer does no work. Keep it awake for long agent runs.
The verification code does not match
Section titled “The verification code does not match”Do not approve it and do not guess. A relay may be sitting between the phone and the computer.
- Deny the request at the computer.
remotxai pair requestslists it, andremotxai pair deny <ref>denies it. - Run
remotxai upon the computer and sign in again, or, on a computer that runs withREMX_LEGACY_PAIRING=1, open a fresh pairing window. - Start again on the phone. A legacy pairing shows a fresh code.
remotxai pair requestsremotxai pair deny <ref>remotxai pair enable 5mremotxai pairIf the code still does not match, stop. Check that the phone and the computer use the remotxai service you expect.
The phone says the computer isn’t in an organisation
Section titled “The phone says the computer isn’t in an organisation”New pairing is off by default, so the phone says This computer isn’t in an organisation. On the computer, run remotxai up and sign in, then tap Retry on the phone.
remotxai upTo pair a phone directly instead, set REMX_LEGACY_PAIRING=1 in the daemon’s environment, then run remotxai pair and leave it running (or remotxai pair enable 10m). remotxai pair enable also still opens the window that approves a scope change for a device already paired.
The pairing request timed out
Section titled “The pairing request timed out”Nobody approved it within 3 minutes. Tap Start a new request on the phone and run remotxai pair approve <ref> on the computer within 3 minutes. A new device only reaches the computer through remotxai up, or through a pairing window when the daemon runs with REMX_LEGACY_PAIRING=1. A computer restart also ends pending requests.
remotxai pair requestsremotxai pair approve <ref>remotxai status or remotxai pair hangs
Section titled “remotxai status or remotxai pair hangs”The service may be reconnecting. Wait a minute and retry. If it keeps failing, check the log and run remotxai doctor:
remotxai statusremotxai logs -n 100remotxai doctorThe agent is unavailable
Section titled “The agent is unavailable”The app says an agent can’t start. In the terminal where you installed remotxai, check that it’s installed:
command -v claudecommand -v codexcommand -v piYou only need the one you use. Install it and sign in, then run remotxai service install so the service finds it. This restarts the service and stops running sessions, so finish active work first.
I get no notifications
Section titled “I get no notifications”- Notifications are blocked in this browser. Allow them in the phone’s settings.
- This browser cannot receive push notifications. On iPhone, add the app to the home screen first. See Install the app on your phone.
- This computer can’t send notifications yet. Upgrade remotxai on it.
- None arrive while the app is open on screen.
remotxai upgradeThen tap Notify this device again. More: Notifications.
An attachment is refused
Section titled “An attachment is refused”The app gives the reason. Usually the file is over 32 MiB, the message’s files total over 64 MiB, the file is empty or the agent can’t read that type. See Files and attachments. Fix or replace the file and resend. On an older remotxai, upgrade first:
remotxai upgradeA profile switch did not work
Section titled “A profile switch did not work”The app says The agent didn’t start under the new profile, so the session went back. Nothing was lost. Check that the profile’s login still works on the computer, run remotxai doctor, then retry. If the app says an earlier switch didn’t finish, check which account is running. Then clear the flag with Clear recovery flag on an admin phone, or on the computer. See Profiles and accounts.
remotxai doctorremotxai sessions clear-switch-recovery <session-id>The background service is not running
Section titled “The background service is not running”remotxai service statusremotxai service startremotxai logs -n 100If it isn’t installed, run remotxai service install. If it keeps stopping, remotxai doctor and the log name the cause. On a new computer it’s often that no agent is installed (claude, codex or pi). The log then says no coding agent found. See The agent is unavailable.
An upgrade broke something
Section titled “An upgrade broke something”Go back to the previous version:
remotxai service rollbackAfter a rollback, a release downloaded for the upgrade you undid is never applied by itself, because the computer only applies a release newer than the one it runs. The daemon removes such a leftover when it starts, and remotxai status removes it too, with a line saying so. To go back to an older release on purpose, use remotxai service rollback or remotxai upgrade --allow-downgrade.
Still stuck
Section titled “Still stuck”Collect these:
remotxai doctorremotxai logs -n 100remotxai diagnosticsremotxai diagnostics writes a redacted remotxai-diagnostics-<timestamp>.tar.gz in the current folder. Remove any tokens or personal names before you share it. Email [email protected] only for security issues.