Help

Troubleshooting

Most problems are one of five things. Check the dot in the app first, then the dashboard, then the error text Claude reports.

The phone shows “Disconnected”#

Just paired on Wi-Fi? Some home routers cache a failed DNS lookup for ten minutes. Pause and resume from the app's notification, or switch to mobile data for a moment.
Battery exemption revoked. The status screen warns about this. Settings → Apps → PhoneBridge → Battery → Unrestricted.
Removed from the dashboard. The app shows Not paired rather than Disconnected. Pair again.
Clock skew. The signature includes a timestamp with a sixty-second window. Automatic date and time should be on.

Claude says the device is offline#

That is JSON-RPC error -32001 with the last time the relay saw the phone. The phone's dot will be grey. Fix the connection above. A client can connect and list tools while the phone is offline, because the relay answers initialize from cache; the first real call is where it shows.

Claude says the device timed out#

Error -32002: the phone was connected but did not answer within thirty seconds. Usually the phone was asleep deeply enough that the call waited for a wake-up, or a confirmation prompt was open and nobody tapped it. Ask again. If it persists, the socket is probably half-dead; the phone replaces it on its next ping.

“denied” or “confirmation_timeout”#

The policy engine said no, or you did not tap Approve within sixty seconds. The audit log in the app shows which rule fired. To let a number through permanently, add it to contacts or to the allowlist in the Policy screen. A contact Claude created still needs one approved send before it counts.

“permission_missing”#

The app lacks an Android permission. Settings → Apps → PhoneBridge → Permissions. SMS, Phone, Call logs and Contacts each back a group of tools.

401 from the relay#

The key or token is wrong, revoked, expired, or its phone has been removed. OAuth tokens renew themselves; if a connector is stuck, disconnect and reconnect it. API keys never expire, so a 401 on one means it was revoked or its phone was removed: mint a new one.

402 subscription_required#

The account has no active subscription. Phones stay paired and keys stay valid; subscribing on the dashboard restores service immediately with no re-pairing.

Pairing fails#

Codes expire after ten minutes and work once. Press Add phone again.
limit_reached means the plan's phone cap. Remove a phone you no longer use.
Five bad codes in ten minutes from one address earns a short lockout.

Check spam, then wait a minute; links are limited to five per ten minutes per address. The link works once and for fifteen minutes. Mail clients that preview links do not consume it, because the page needs a button press.

Play Protect blocked the install#

See the install page: More details → Install anyway, or pause Play Protect for one install.

Still stuck#

Open an issue on GitHub with the error text Claude reported, the app version from the status screen, and the relay log lines around the time, which contain no message content. Hosted customers can also write to phonebridgesupport@gmail.com.