Troubleshooting
Use this page when SimDeck does not start, cannot see a device, shows a bad stream, or falls back to the wrong inspector.
First checks
simdeck --version
xcode-select -p
simdeck service status
simdeck listIf the background service may be stale:
simdeck service stop
simdeckServer will not start
Port is already in use
bind HTTP listener on 127.0.0.1:4310Use another port:
simdeck -p 4320 --openOr find the listener:
lsof -nP -iTCP:4310 -sTCP:LISTENIf it is an old service:
simdeck service stopsimdeck prints nothing for minutes on Windows
Earlier Windows builds let child processes inherit the service's listening socket. If the service exited while the adb server or an emulator it started was still running, port 4310 stayed open with nothing answering, and the next simdeck run waited on it before starting a fresh service on another port. Stop the orphaned holder and run simdeck again:
adb kill-serverNewer builds keep the listener private to the service and give up on a silent port after a few seconds.
Windows reports a missing libstdc++-6.dll or vcruntime140.dll
The Windows binary must not depend on toolchain runtime DLLs. A build that does fails from PowerShell or cmd with exit code 0xC0000135 (and only starts inside Git Bash when the MinGW DLLs happen to be on PATH). Released builds target x86_64-pc-windows-msvc with a static CRT; a source build should set SIMDECK_BUILD_TARGET=x86_64-pc-windows-msvc, which npm run build:cli handles by adding +crt-static and refusing to package a binary that still imports those DLLs.
Native binary is missing
Reinstall from npm:
npm install -g simdeck@latestFrom a source checkout:
npm run build:cliSource build fails
Check the common prerequisites:
xcode-select --install
rustc --version
node --versionBuilds must run on macOS because SimDeck links macOS simulator frameworks.
Device does not boot or list
simdeck list hangs or returns stale data
Restart Apple's simulator service:
simdeck core-simulator restart
simdeck listWrong Xcode is selected
sudo xcode-select -s /Applications/Xcode.app
simdeck listOr run one command with an explicit developer directory:
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer simdeck listAndroid emulator is missing
Confirm Android SDK tools are on PATH:
adb devices
emulator -list-avdsAndroid IDs in SimDeck use android:<avd-name>.
Stream is black or stuck
iOS simulators require macOS
iOS simulators require macOS. This SimDeck build for Windows can boot, control, and stream Android emulators, but the iOS simulator bridge is only available on macOS.This is expected on the Windows and Linux builds. They link a stub instead of the macOS native bridge that owns iOS simulator control and the VideoToolbox and x264 encoders. Android emulators still boot, stream, and accept input on those hosts through the built-in OpenH264 software encoder. Use a Mac for iOS simulators, or pair a Windows or Linux browser with a SimDeck service running on a Mac. Check liveVideo.iosSimulator in GET /api/health when scripting against the service.
Android stream is slow on Windows or Linux
Those builds encode with OpenH264 in software. Lower the encoded size first, then the frame rate:
simdeck service restart --stream-quality lowGET /api/metrics lists androidEncoders[].encoder.native with latestEncodeLatencyUs and skippedFrames; if encode latency stays above the frame interval, the host CPU cannot keep up with the selected profile.
Timed out waiting for the first frame
Try software encoding:
simdeck service restart --video-codec softwareFor CI or virtualized Macs:
simdeck service restart --video-codec software --stream-quality ci-softwareStream stutters or refreshes repeatedly
Lower the quality:
simdeck service restart --stream-quality lowCheck metrics:
curl http://127.0.0.1:4310/api/metricsIf frames_dropped_server keeps climbing, the client or network cannot keep up. Move closer to the host, reduce quality, or switch to software encoding.
For Android emulator streams, SimDeck uses the emulator -share-vid shared display surface. If Android video never starts, confirm adb devices shows the emulator as device, that it has fully booted, and that externally launched emulators were started with -share-vid. SimDeck-owned Android boots add the flag automatically and default to --android-gpu host; try simdeck service restart --android-gpu auto or --android-gpu swiftshader_indirect only when host rendering is unstable.
Browser cannot establish WebRTC
Use ?stream=webrtc while testing to make transport selection explicit:
http://127.0.0.1:4310?stream=webrtcFor routed remote sessions, configure TURN as described in Video and streaming.
Inspector looks wrong
describe returns accessibility instead of framework data
The fallback is expected when no in-app inspector is available. Check:
- The app with the inspector is foregrounded.
- The app was built in debug mode.
- The inspector package starts before the app UI boots.
- The app is pointing at the active SimDeck port.
Use a forced source to see the failure reason:
simdeck describe --source nativescript
simdeck describe --source react-native
simdeck describe --source flutter
simdeck describe --source uikitNativeScript inspector does not connect
- Call
startSimDeckInspector({ port: 4310 })before bootstrap. - For Angular, call it before
runNativeScriptAngularApp(...). - Confirm the simulator app can reach
http://127.0.0.1:4310/api/health.
React Native source locations are missing
Use a development build. Production bundles usually strip React debug source metadata.
Flutter source locations are missing
Run a debug build with widget creation tracking. Flutter enables this by default for normal debug runs.
LAN browser cannot connect
Start SimDeck with a LAN bind and reachable advertised host:
simdeck --bind 0.0.0.0 --advertise-host 192.168.1.50 --openFor native iOS pairing, prefer:
simdeck pairThen check:
- The remote browser opens
http://192.168.1.50:4310. - macOS Firewall allows the port.
- The pairing code matches the current service.
- API scripts send the service token.
See LAN access.
Logs to include in issues
Include:
simdeck --version- macOS version
- Xcode version
- The command you ran
- Service output, or
build/cli.logwhen usingnpm run dev simdeck service statuswithout sharing the token publicly