Troubleshooting

The app's failure screens link straight to the sections below. Each one names the side that's wrong, phone or machine, and the command that proves it.

The app can't reach that machine

Check the phone first. Open Tailscale on the phone and make sure it's connected: the app talks directly to your machine over the tailnet, so with Tailscale off there is no route at all. This is the most common cause and the easiest to forget after a VPN toggle.

Then the machine. A sleeping laptop drops off the tailnet, so wake it and check it shows as connected in tailscale status. While you're there, confirm the bridge itself is up:

$ outridr status
$ curl "http://$(tailscale ip -4):8674/health"

Last, look at the hostname in the app's settings for typos. It should be the machine's Tailscale name (or Tailscale IP), not a LAN name that only resolves on your home network. On a Mac the tailscale CLI isn't on PATH by default; use /Applications/Tailscale.app/Contents/MacOS/Tailscale for the commands above.

The bridge rejected this hostname

A bridge with no token configured answers 421 Misdirected Request when it doesn't recognize the hostname the app connected with. Without a token it only accepts addresses it can verify — an IP literal, localhost, or a full .ts.net MagicDNS name — as a defense against DNS rebinding. A short name like gondor fails that test even though it resolves fine.

Two ways out:

• Run outridr pair on the machine and scan the QR. Pairing sets a token, and with a token configured the hostname check no longer applies: the token itself is the proof the request is yours.
• Or keep going tokenless and give the app the machine's full .ts.net name, or its Tailscale IP from tailscale ip -4.

Pair. You get a working hostname and the extra lock in one step.

Version or protocol mismatch

Three parts have to agree: the app, the outridr bridge, and herdr. The app speaks herdr's socket API protocol 16, and since outridr 0.6.0 the bridge identifies itself and its version before any token is checked, which is how the app can tell you which side is outdated instead of failing vaguely.

To update the bridge, on the machine:

$ npm install -g outridr@latest

Then restart the service: systemctl --user restart outridr on Linux, or run outridr install again on either platform, which regenerates the service around the new version.

To update herdr, use the installer or package manager you installed it with; see herdr's install docs. herdr status reports the protocol the running server speaks. And if the old side is the app, update it from the store you installed it from.