droidline

Troubleshooting connections

What to check when a phone does not show up, will not pair, or keeps dropping.

Start with these two:

droidline doctor
droidline serve --verbose

doctor checks that the server answers, the ports are free, phones are paired and the PC has a network address. --verbose logs every connection attempt, including rejected handshakes.

The app does not find the PC on Wi-Fi

  • Allow droidline through the Windows firewall on private networks, and make sure the Wi-Fi is set to Private.
  • Guest networks and some mesh routers isolate clients. Use the main network or scan the QR code instead.
  • Phone and PC on different subnets: pair with the QR code, which carries the PC's address.

The pairing code is refused

PAIRING_FAILED means no phone is waiting with that code. Codes expire after 5 minutes; tap Pair on this Wi-Fi again for a new one. A QR code is valid for 10 minutes and for one phone; run droidline pair again for another.

The app says the PC rejected it

The PC no longer knows this phone, usually because it was removed with droidline revoke, or the server's folder was deleted or moved. Pair the phone again.

The phone keeps disconnecting

  • Battery optimization: set the app to not restricted, and allow it in any brand-specific sleeping-apps or auto-launch list.
  • Mobile data with a weak signal reconnects often; that is expected, and nothing runs twice.
  • A route that works on Wi-Fi but not outside means the phone has no remote address yet. Let it connect on Wi-Fi once after you configure the address, or pair again.

Port forwarding does not work

  • Your connection may be behind carrier-grade NAT; use a tunnel or a relay.
  • After deleting tls.crt, the certificate changed and phones refuse it; pair them again.

Relay problems

SymptomCause
The server log shows 401 from the relayRELAY_TOKEN on the relay and the token given to droidline relay set differ
503 from a Workers relayThe RELAY_TOKEN secret is not set yet
409 when a phone pairs through the relayThat phone is already connected with its own ticket; this is expected
The phone is dropped with code 4008It exceeded 50 lines per second; update the app

Tunnel address changed

Quick tunnels get a new address each time they start. Update remote.addresses, restart the server, and let phones connect on Wi-Fi once, or use a named tunnel with a fixed host name.