Troubleshooting

Find the symptom below, or start with tapflow doctor on the Mac where it happens.

Start with tapflow doctor

On the agent Mac, tapflow doctor checks Node.js, the port, Xcode and the simulator, the Android SDK and an AVD, and prints what to fix for each failure. Pass ios or android to check one platform. The checks are listed in the CLI reference, and each failure is explained under tapflow doctor failures.

tapflow doctor
tapflow doctor ios

Find your symptom

Symptom	See
An agent does not appear in the dashboard, or cannot connect	Agent cannot connect to the relay
tapflow agent start says an agent is already running	It says an agent is already running
The relay reads a configuration or database you did not expect	Unexpected configuration or database
Opening an iOS build fails with spawn unknown error	iOS simulator
The iOS simulator does not boot	Service version mismatch, cannot be located on disk
The Android stream does not start	Android emulator
An upload fails with 400	Builds & uploads
An APK does not install on an Apple Silicon Mac (INSTALL_FAILED_NO_MATCHING_ABIS)	Builds & uploads
The stream lags, stutters or looks blurry	Stream & sessions
A session ends by itself	Session ends automatically
A device will not go offline	Network control
An invitation or password reset link does not work	Sign-in & accounts
Everyone was signed out after an upgrade	Signed out after upgrading

View the relay's 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