Skip to content

Troubleshooting

iPhone LiveKit Call Times Out Over Tailscale

Symptoms:

  • The iOS app can reach the local CLI API.
  • POST /api/livekit-room-token/ returns 200.
  • The app logs a LiveKit URL such as ws://<machine>.tailnet-name.ts.net:7880.
  • The LiveKit agent joins the room, but the iPhone fails during room.connect or times out before publishing the microphone.

This usually means signaling is working but WebRTC media cannot complete ICE. One known cause is LiveKit advertising the machine's Tailscale IP while its UDP media socket is only bound to loopback.

Check the local LiveKit listeners:

lsof -nP -iTCP:7880 -iTCP:7881 -iUDP:7882

For Tailscale iPhone calls, LiveKit should have UDP listeners on both loopback and the machine's Tailscale addresses, for example:

UDP 127.0.0.1:7882
UDP 100.x.y.z:7882
UDP [fd7a:115c:a1e0::...]:7882
TCP *:7881 (LISTEN)
TCP 127.0.0.1:7880 (LISTEN)

If UDP is only bound on 127.0.0.1:7882, regenerate and reload the launchd service wrappers from a version of openbase-coder that includes the Tailscale interface fix:

openbase-coder services regenerate
openbase-coder services install

Then restart the LiveKit services:

openbase-coder restart --service livekit-server
openbase-coder restart --service livekit-agent

For new installs, openbase-coder setup generates the corrected LiveKit wrapper automatically. Existing installs need regenerated wrappers because launchd runs the generated shell scripts in ~/.openbase/launchd/.

The corrected wrapper derives LIVEKIT_INTERFACE from the interface that owns LIVEKIT_NODE_IP, rather than trusting a route lookup while Tailscale is still settling. You can still override the values in ~/.openbase/.env when needed:

LIVEKIT_NETWORK_MODE=tailscale
LIVEKIT_NODE_IP=100.x.y.z
LIVEKIT_INTERFACE=utunN
LIVEKIT_BIND_IP=127.0.0.1
LIVEKIT_TCP_PORT=7881
LIVEKIT_UDP_PORT=7882

Voice Route Exit Returns 502 With Invalid LiveKit URL

Symptoms:

  • POST /api/livekit-voice-route/exit/ returns 502 Bad Gateway.
  • The Django log contains ValueError: Invalid URL: port can't be converted to integer.
  • The bad URL contains Tailscale CLI error text, for example http://The Tailscale CLI failed to start: ...:7880/....

This means the Django launchd service started while tailscale ip -4 returned an error string instead of an IPv4 address, and that string was captured into LIVEKIT_URL.

Regenerate wrappers and restart Django:

openbase-coder services regenerate
openbase-coder restart --service django-cli

The service wrapper validates the derived Tailscale IPv4 address before exporting LIVEKIT_URL. If Tailscale cannot provide a valid IPv4 address in tailscale mode, the service now exits with a clear startup error instead of running with a malformed LiveKit URL.

Enable iOS Auth Diagnostics

iOS AuthDiagnostics logging is disabled by default. Enable it only while debugging auth, CLI API, or LiveKit call setup.

You can enable it from code with:

AuthDiagnostics.setEnabled(true)

Or set the process environment variable in an Xcode scheme:

OPENBASE_AUTH_DIAGNOSTICS=1

When enabled, diagnostics intentionally do not redact backend URLs, LiveKit URLs, or room names so local connectivity issues can be debugged directly. Do not leave it enabled for routine development sessions unless you need the extra logs.