Troubleshooting

Problems are grouped by area, one page each:

• Install & agents
• iOS simulator
• Android emulator
• Builds & uploads
• Stream & sessions
• Sign-in & accounts

Viewing logs

On the relay host, inspect its activity with the commands below. The relay does not show its logs to other machines.

tapflow logs
tapflow logs --lines 200

Running under Docker, a CLI outside the container counts as remote; use docker compose logs instead.

Moved sections

Sections that used to be on this page now live on these pages.

• Install & agents
  • Agent connection issues
  • It says an agent is already running
  • Agent cannot connect to the relay
  • tapflow doctor failures
  • All iOS checks fail
  • Xcode not found — Xcode is not installed
  • Xcode not found — Xcode is installed but xcode-select is not configured
  • No simulator is running
  • adb not found
  • tapflow init says CONFIG KEPT
  • The relay is using a configuration or database you did not expect
• iOS simulator
  • Opening a build fails with spawn unknown error
  • iOS Simulator service version mismatch
  • iOS Simulator fails to boot — "cannot be located on disk"
  • iOS 17 and earlier — Korean text splits into individual characters
• Builds & uploads
  • iOS build upload errors
  • 400 error on upload
  • INSTALL_FAILED_NO_MATCHING_ABIS — APK not compatible with Apple Silicon emulator
  • An APK upload shows as 'Unversioned' or merges into the wrong app
• Android emulator
  • Android emulator issues
  • Stream does not start or encoder crashes
  • Colors look different from the emulator (less saturated)
  • Emulator is slow when the Mac is unattended
• iOS network extension
  • iOS: the network extension is not installed
  • 1. Install it
  • 2. Approve it
  • 3. When a restart is needed
  • Checking what the Mac has
  • If it still does not work
  • iOS: the Mac lost its network while the filter was being replaced
  • iOS: a device that was offline came back on the network by itself
• Stream & sessions
  • Session issues
  • Session ends automatically
  • Stream lag or stuttering
  • Prefer a wired LAN
  • Periodic hitching every ~0.5s on Wi-Fi (AWDL)
  • Host CPU / RAM pressure
  • Display sleep
  • Blurry or low-resolution stream on LAN
• Sign-in & accounts
  • Auth issues
  • tapflow admin init fails (Already initialized)
  • Invitation link expired
  • Password reset link expired