Specchio Documentation

Appearance

Troubleshooting ​

This comprehensive troubleshooting guide helps you diagnose and fix common issues with Specchio.

Table of Contents ​

  1. Quick Diagnostics
  2. Installation Issues
  3. Connection Issues
  4. Display Issues
  5. Input Issues
  6. Performance Issues
  7. Error Messages

Quick Diagnostics ​

Before diving into specific issues, run this quick diagnostic script to identify problems:

bash
#!/bin/bash
# Save this as specchio-diagnostics.sh and run with: bash specchio-diagnostics.sh

echo "======================================"
echo "Specchio Diagnostics v1.0"
echo "======================================"
echo ""

# Color codes
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Check function
check() {
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}✓ OK${NC}: $1"
    else
        echo -e "${RED}✗ FAILED${NC}: $1"
    fi
}

# 1. macOS Version
echo "1. Checking macOS version..."
MACOS_VERSION=$(sw_vers -productVersion)
echo "   Version: $MACOS_VERSION"
if [[ "$MACOS_VERSION" > "14.0" ]] || [[ "$MACOS_VERSION" == "14.0" ]]; then
    check "macOS 14.0+ installed"
else
    echo -e "${RED}   ✗ macOS 14.0 (Sonoma) or later required${NC}"
fi
echo ""

# 2. Xcode Installation
echo "2. Checking Xcode..."
if [ -d "/Applications/Xcode.app" ]; then
    check "Xcode.app found"
    xcodebuild -version 2>/dev/null | sed 's/^/   /'
else
    echo -e "${RED}   ✗ Xcode.app not found in /Applications/${NC}"
fi
echo ""

# 3. Xcode License
echo "3. Checking Xcode license..."
if xcodebuild -checkFirstLaunchStatus 2>&1 | grep -q "accepted"; then
    check "Xcode license accepted"
else
    echo -e "${YELLOW}   ⚠ Xcode license may not be accepted${NC}"
    echo "   Run: sudo xcodebuild -license accept"
fi
echo ""

# 4. iOS SDK
echo "4. Checking iOS SDK..."
if xcodebuild -showsdks 2>/dev/null | grep -q "iphoneos"; then
    check "iOS SDK installed"
    xcodebuild -showsdks 2>/dev/null | grep "iphoneos" | head -1 | sed 's/^/   /'
else
    echo -e "${RED}   ✗ iOS SDK not found${NC}"
    echo "   Install via: Xcode → Settings → Platforms → iOS → Get"
fi
echo ""

# 5. Code Signing Certificate
echo "5. Checking Apple Development certificate..."
CERT_COUNT=$(security find-identity -v -p codesigning 2>/dev/null | grep -c "Apple Development")
if [ "$CERT_COUNT" -gt 0 ]; then
    check "Apple Development certificate found ($CERT_COUNT certificate(s))"
    security find-identity -v -p codesigning 2>/dev/null | grep "Apple Development" | head -1 | sed 's/^/   /'
else
    echo -e "${RED}   ✗ No Apple Development certificate found${NC}"
    echo "   Create via: Xcode → Settings → Accounts → Manage Certificates → + → Apple Development"
fi
echo ""

# 6. Connected iOS Devices
echo "6. Checking for iOS devices..."
DEVICE_COUNT=0
if command -v xcrun &> /dev/null; then
    DEVICES=$(xcrun devicectl list devices 2>&1)
    DEVICE_COUNT=$(echo "$DEVICES" | grep -c "iPhone\|iPad")
    if [ "$DEVICE_COUNT" -gt 0 ]; then
        check "Found $DEVICE_COUNT iOS device(s)"
        echo "$DEVICES" | grep "iPhone\|iPad" | sed 's/^/   /'
    else
        echo -e "${YELLOW}   ⚠ No iOS devices found${NC}"
        echo "   Connect your iPhone via USB and ensure it's unlocked"
    fi
else
    echo -e "${YELLOW}   ⚠ xcrun not found - Xcode tools may not be installed${NC}"
fi
echo ""

# 7. iproxy (bundled tool)
echo "7. Checking iproxy (bundled)..."
if [ -f "SupportingFiles/BundledTools/iproxy" ]; then
    check "iproxy binary found in bundled tools"
else
    echo -e "${YELLOW}   ⚠ iproxy not found in bundled tools${NC}"
fi
echo ""

# 8. libimobiledevice (bundled)
echo "8. Checking libimobiledevice (bundled)..."
if find SupportingFiles/BundledTools -name "*.dylib" | grep -q libimobiledevice; then
    check "libimobiledevice libraries found"
else
    echo -e "${YELLOW}   ⚠ libimobiledevice libraries not found${NC}"
fi
echo ""

# 9. Disk Space
echo "9. Checking disk space..."
DISK_FREE=$(df -h / | awk 'NR==2 {print $4}')
DISK_FREE_GB=$(df -h / | awk 'NR==2 {print $4}' | sed 's/[^0-9.]//g')
echo "   Available: $DISK_FREE"
if (( $(echo "$DISK_FREE_GB > 20" | bc -l) )); then
    check "Sufficient disk space (>20 GB)"
else
    echo -e "${YELLOW}   ⚠ Low disk space - recommend at least 20 GB free${NC}"
fi
echo ""

# 10. Network (for WiFi debugging)
echo "10. Checking network configuration..."
if command -v networksetup &> /dev/null; then
    WIFI_NAME=$(networksetup -getairportnetwork en0 2>/dev/null | awk -F': ' '{print $2}')
    if [ ! -z "$WIFI_NAME" ]; then
        check "Connected to WiFi: $WIFI_NAME"
    else
        echo -e "${YELLOW}   ⚠ Not connected to WiFi${NC}"
    fi
else
    echo -e "${YELLOW}   ⚠ Could not check WiFi status${NC}"
fi
echo ""

echo "======================================"
echo "Diagnostics complete!"
echo "======================================"
echo ""
echo "For more detailed diagnostics, see the [Diagnostic Commands](/diagnostics) page."

Run this script:

bash
# Create and run the script
cat > specchio-diagnostics.sh << 'EOF'
[paste the script above]
EOF

chmod +x specchio-diagnostics.sh
./specchio-diagnostics.sh

Installation Issues ​

Xcode Won't Install ​

Symptoms:

  • App Store shows error during download
  • Installation hangs or fails
  • "Not enough disk space" error

Solutions:

  1. Check disk space:

    bash
    df -h /

    You need at least 20 GB free.

  2. Clear App Store cache:

    bash
    rm -rf ~/Library/Caches/com.apple.appstore
rm -rf ~/Library/Caches/com.apple.instruments

    Then restart your Mac and try again.

  3. Download via browser:

Xcode License Won't Accept ​

Symptoms:

  • sudo xcodebuild -license accept shows error
  • Xcode keeps asking to accept license

Solutions:

  1. Try via GUI:

    • Open Xcode
    • Click "Agree" when prompted
    • Wait for additional components to install

  2. Remove license flag and retry:

    bash
    sudo rm /Library/Preferences/com.apple.dt.Xcode.plist
sudo xcodebuild -license accept

  3. Check Xcode installation:

    bash
    ls -la /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild

Certificate Creation Fails ​

Symptoms:

  • "Manage Certificates" button is greyed out
  • Certificate creation error
  • No certificate appears after creation

Solutions:

  1. Verify Apple ID is signed in:

    bash
    # Check for Apple ID in Xcode preferences
defaults read com.apple.dt.Xcode IDEDeveloperExtrasPresent

  2. Remove and re-add Apple ID:

    • Open Xcode → Settings → Accounts
    • Select your Apple ID → Click "-"
    • Click "+" → Add Apple ID again
    • Then try creating certificate

  3. Check for certificate manually:

    bash
    security find-identity -v -p codesigning | grep "Apple Development"

  4. Reset certificate database (last resort):

    bash
    security default-keychain -s login.keychain
security unlock-keychain

Connection Issues ​

Device Not Detected ​

Symptoms:

  • iPhone doesn't appear in Specchio device list
  • "No devices found" error

Solutions:

  1. Verify device is detected by system:

    bash
    xcrun devicectl list devices

    If empty:

    • Try different USB cable
    • Try different USB port
    • Restart iPhone and Mac
    • Ensure iPhone is unlocked

  2. Check device trust:

    • On iPhone: Settings → General → VPN & Device Management
    • Look for your Mac's certificate
    • If not present, reconnect via USB and tap "Trust"

  3. Reset trust on iPhone:

    • Settings → General → Transfer or Reset iPhone → Reset
    • Choose "Reset Location & Privacy"
    • Reconnect to Mac and trust again

iproxy Connection Fails ​

Symptoms:

  • "Could not establish iproxy connection"
  • Port 8100 not accessible

Solutions:

  1. Check if iproxy is running:

    bash
    ps aux | grep iproxy

  2. Kill existing iproxy processes:

    bash
    pkill iproxy

  3. Manually test iproxy:

    bash
    # Find device UDID
xcrun devicectl list devices

# Manually run iproxy
./SupportingFiles/BundledTools/iproxy 8100 8100

  4. Test connection:

    bash
    curl http://localhost:8100/status

WiFi Connection Not Working ​

Symptoms:

  • iPhone not visible via WiFi
  • Connection drops when USB unplugged
  • "Device not found on network"

Solutions:

  1. Verify same network:

    bash
    # Get Mac's IP
ipconfig getifaddr en0

# Get iPhone's IP (from device list)
xcrun devicectl list devices

    Both should be on same subnet (e.g., 192.168.1.x)

  2. Re-enable WiFi debugging:

    • Open Xcode
    • Window → Devices and Simulators
    • Check "Connect via network"
    • Unplug USB - device should remain visible

  3. Check network allows device discovery:

    bash
    # Browse for iOS devices on network
dns-sd -B _apple-mobdev2._tcp local.

    Wait 10-15 seconds for results.

  4. Try different network:

    • Some corporate/guest networks block device-to-device communication
    • Try a home WiFi network

Display Issues ​

Black Screen / No Video ​

Symptoms:

  • Connection succeeds but screen is black
  • No updates displayed

Solutions:

  1. Test WDA screenshot endpoint:

    bash
    curl http://localhost:8100/screenshot --output test.png
open test.png

    If this works, WDA is functioning - issue is with Specchio.

  2. Check device is not locked:

    • Wake your iPhone
    • Enter passcode if needed
    • Keep it awake

  3. Try different display mode:

    • Switch from USB Video to Screenshot mode
    • Or try Lite mode

  4. Check WDA status:

    bash
    curl http://localhost:8100/status | jq

    Look for "state": "success"

Poor Quality / Low Resolution ​

Symptoms:

  • Blurry or pixelated display
  • Wrong aspect ratio
  • Small window size

Solutions:

  1. Check actual screenshot quality:

    bash
    curl http://localhost:8100/screenshot --output test.png
file test.png
# Should show iPhone native resolution

  2. Try USB Video mode (if on WiFi):

    • Connect via USB
    • Switch to USB Video mode for best quality

  3. Check display scaling in Specchio:

    • View → Actual Size (100%)
    • View → Fit to Window

Display Lag / High Latency ​

Symptoms:

  • Noticeable delay between iPhone and display
  • Slow frame rate
  • Choppy updates

Solutions:

  1. Test current FPS:

    • Enable "Show FPS" in Specchio settings
    • Check what frame rate you're getting

  2. Switch to faster mode:

    • USB Video: 30-60 FPS
    • Screenshot: 5-15 FPS
    • Lite: 2-5 FPS

  3. Check CPU usage:

    bash
    top -o cpu | grep -E "Specchio|Xcode"

    If CPU is high, try Lite mode.

  4. Use USB instead of WiFi:

    • WiFi adds 10-50ms latency
    • USB has minimal latency

Input Issues ​

Clicks Not Registering ​

Symptoms:

  • Clicking doesn't trigger taps on iPhone
  • No response to mouse input

Solutions:

  1. Test WDA input directly:

    bash
    # Tap at center of screen
curl -X POST http://localhost:8100/wda/tap \
  -H "Content-Type: application/json" \
  -d '{"x": 0.5, "y": 0.5}'

  2. Verify coordinate mapping:

    • Check Specchio logs for coordinate values
    • Ensure they're between 0.0 and 1.0

  3. Check WDA session:

    bash
    curl http://localhost:8100/status

    Look for active session.

Keyboard Not Typing ​

Symptoms:

  • Typing on Mac keyboard doesn't appear on iPhone
  • Missing characters
  • Wrong characters

Solutions:

  1. Test WDA keyboard input:

    bash
    # Type "Hello"
curl -X POST http://localhost:8100/wda/keys \
  -H "Content-Type: application/json" \
  -d '{"value": ["Hello"]}'

  2. Click into text field first:

    • Must tap a text field before typing
    • iOS keyboard should be dismissed

  3. Check keyboard layout:

    • Settings → Input → Keyboard Layout
    • Match to your physical keyboard

Gestures Not Working ​

Symptoms:

  • Pinch/zoom doesn't work
  • Swipe gestures don't respond
  • Multi-touch doesn't work

Solutions:

  1. Test gesture endpoint:

    bash
    # Test swipe
curl -X POST http://localhost:8100/wda/swipe \
  -H "Content-Type: application/json" \
  -d '{"fromX": 0.5, "fromY": 0.8, "toX": 0.5, "toY": 0.2}'

  2. Check modifier keys:

    • Ensure you're holding correct keys (⌘ for pinch, etc.)
    • Check Input settings for key bindings

  3. Some apps don't support gestures:

    • Try in different apps (Photos, Maps)

Performance Issues ​

High CPU Usage ​

Symptoms:

  • Specchio using lots of CPU
  • Mac fans running loud
  • Battery draining quickly

Solutions:

  1. Check CPU usage:

    bash
    top -o cpu | grep Specchio

  2. Switch to more efficient mode:

    • Lite mode uses least CPU
    • USB Video uses hardware acceleration (efficient)
    • Screenshot mode is middle ground

  3. Reduce frame rate:

    • Settings → Display → Max FPS
    • Lower to 15 or 30 FPS

High Memory Usage ​

Symptoms:

  • Specchio using lots of RAM
  • System slowdowns
  • Swapping

Solutions:

  1. Check memory usage:

    bash
    ps aux | grep Specchio | awk '{print $6}'

  2. Restart Specchio:

    • Memory may accumulate over time
    • Periodic restarts help

  3. Use Lite mode:

    • Lowest memory footprint
    • No image decoding overhead

Error Messages ​

"WebDriverAgent failed to launch" ​

Cause: WDA installation or startup failure

Solutions:

bash
# Check WDA status
curl http://localhost:8100/status

# Try manually launching WDA
xcodebuild test \
  -project /path/to/WebDriverAgent/WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'id=<YOUR_DEVICE_UDID>' \
  CUSTOM_APP_BUNDLE_PATH=/path/to/WebDriverAgent.app

"Could not establish session" ​

Cause: WDA server not responding

Solutions:

bash
# Restart iproxy
pkill iproxy
iproxy 8100 8100 &

# Create new session
curl -X POST http://localhost:8100/session \
  -H "Content-Type: application/json" \
  -d '{"capabilities": {"deviceName": "iPhone", "platformName": "iOS"}}'

"Screenshot capture failed" ​

Cause: WDA screenshot endpoint error

Solutions:

bash
# Test screenshot manually
curl http://localhost:8100/screenshot --output test.png

# Check device is not locked
# (wake and unlock iPhone)

# Try different display mode

Getting Help ​

If none of these solutions work:

  1. Run full diagnostics: See Diagnostic Commands
  2. Check logs: Specchio → View → Show Log
  3. Search existing issues: https://github.com/Alexintosh/Specchio/issues
  4. Create new issue: Include:
    • macOS version
    • Xcode version
    • iOS version
    • Exact error message
    • Diagnostic output

For diagnostic commands you can run, see the Diagnostic Commands page.

Released under the MIT License.

Copyright © 2024-present Alessio Delmonti