> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/zwc456baby/ScrcpyForAndroid/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Diagnose and fix common issues with Scrcpy for Android connections and performance ## Overview This guide helps you resolve common issues when using Scrcpy for Android. Issues are organized by category for quick reference. ## Connection Timeout Errors ### "Connection Timed out 2" This error appears when the socket connection cannot be established within the timeout period. * Target device is not reachable on the network * Firewall blocking ADB port (5555) * Wireless debugging not enabled on target device * Incorrect IP address or port * Target device went to sleep during connection 1. Verify the target device IP address is correct 2. Ensure both devices are on the same network 3. Check that wireless debugging is enabled on the target 4. Try pinging the target device IP from a terminal 5. Restart wireless debugging on the target device 6. Keep target device screen on during connection ```bash Verify Network Connection theme={null} # From a terminal on your local device ping 192.168.0.73 # If ping fails, devices cannot communicate ``` ```bash Check ADB Port theme={null} # Ensure ADB is listening on the correct port adb tcpip 5555 ``` ### Connection Timeout During Handshake If connection starts but times out before showing the screen: **Timeout Configuration:** * Initial connection: 50 attempts × 100ms = 5 seconds * Socket timeout: 5000ms (5 seconds) * Resolution handshake: 10 attempts × 100ms = 1 second If you consistently hit the handshake timeout, the scrcpy-server.jar may not be executing properly on the target device. **Resolution Steps:** 1. Manually verify server jar exists on target: ```bash theme={null} adb -s :5555 shell ls -alh /data/local/tmp/scrcpy-server.jar ``` 2. Check server execution permissions 3. Clear `/data/local/tmp/` and retry connection 4. Restart ADB server on both devices ## ADB Connection Issues ### "Network OR ADB connection failed" This message indicates the ADB connection or server upload failed. **Symptoms:** * Cannot reach target device * Ping fails * Different network subnets **Solutions:** * Ensure both devices on same Wi-Fi network * Check for VPN interference * Disable mobile data during connection * Try connecting to 5GHz band if available **Symptoms:** * Can ping device but ADB fails * "adb devices" shows device as offline * Connection refused errors **Solutions:** * Restart ADB: `adb kill-server && adb start-server` * Re-enable wireless debugging on target * Check ADB port: `adb tcpip 5555` * Verify no other ADB instance is running **Symptoms:** * Server jar upload fails * Cannot write to /data/local/tmp/ **Solutions:** * Ensure wireless debugging is authorized * Check target device for ADB authorization prompt * Grant USB debugging permission if prompted * Remove and re-pair ADB keys ### Repeated Connection Failures The app automatically restarts the ADB server after 3 consecutive failures. You can see connection attempt counter in logs: "连接错误次数: X" (Connection error count: X) **When errors accumulate:** * Error count increments on each failed connection * At 3 errors: `App.startAdbServer()` is called automatically * Manual disconnect resets counter to 0 * Successful connection resets counter to 0 ## Network Problems ### High Latency **Symptoms:** * Slow response to touch input * Video stuttering * Audio out of sync **Diagnosis:** 1. Check your delay control setting (try "High (100ms)") 2. Monitor Wi-Fi signal strength 3. Test with lower resolution/bitrate **Recommended Settings for Poor Networks:** | Setting | Value | | ------------- | ------------------ | | Resolution | 640x360 or 800x448 | | Bitrate | 1 Mbps | | Delay Control | High (100ms) | ### Packet Loss **Symptoms:** * Frequent frame drops * Blocky video artifacts * Choppy playback ```text Frame Dropping Mechanism theme={null} // The app automatically drops frames that exceed delay threshold if (currentTime - (lastOffset + frameTimestamp) >= delayMs) { // Frame is dropped passCount++; } else { // Frame is decoded and displayed passCount = 0; } ``` **Solutions:** * Reduce bitrate to 2 Mbps or 1 Mbps * Lower resolution to reduce bandwidth * Move closer to Wi-Fi router * Switch to 5GHz Wi-Fi if available * Close bandwidth-heavy apps on both devices ## Black Screen Issues ### Screen Stays Black After Connection The most common cause of black screens is orientation mismatch. **What happens:** * App expects portrait, device is landscape (or vice versa) * Video decoder configured for wrong dimensions * Surface cannot render mismatched resolution **Solution:** * Disconnect and return to main screen * Ensure main screen shows portrait orientation * Reconnect to device * Let automatic rotation handle orientation changes The video surface may not be initialized when decoder starts. **Indicators:** * Connection succeeds quickly * No error messages * Touch input works but no video **Solution:** * This is usually transient * Wait 2-3 seconds * If persists, disconnect and reconnect Video decoder may fail to configure with received settings. **Check for:** * Unsupported resolution on local device * SPS/PPS configuration errors * Codec compatibility issues **Solution:** * Try different resolution (1280x720 is widely supported) * Lower bitrate * Restart both apps ### Black Screen After Rotation Rotation requires careful state management: Do not switch to split-screen or floating window mode during connection, as this may cause orientation issues that result in black screen. **If black screen occurs after rotation:** 1. Press back button twice to disconnect 2. App returns to main screen 3. Wait for orientation to stabilize to portrait 4. Reconnect ## Performance Optimization ### Improving Frame Rate Lower resolution reduces encoding/decoding overhead: * Start with 1280x720 for good balance * Reduce to 800x448 if still choppy * Use 640x360 only for very slow devices Match bitrate to network capacity: * Test with 2 Mbps first * Increase to 4 Mbps if stable * Use 6 Mbps only on excellent local networks Balance responsiveness vs. smoothness: * Low (30ms): Fast networks, prioritizes responsiveness * Medium (60ms): Default, good balance * High (100ms): Slow networks, prioritizes smooth playback Free up resources on both devices: * Close unnecessary apps on target device * Close heavy apps on local device * Disable auto-sync and updates ### Reducing Latency **For minimum input lag:** ```text Optimal Settings theme={null} Resolution: 800x448 or 1280x720 Bitrate: 2 Mbps or 4 Mbps Delay: Low (30ms) Network: 5GHz Wi-Fi, close proximity to router ``` **What affects latency:** * **Network latency**: Ping time between devices (check with ping command) * **Encoding delay**: Higher resolution = more encoding time * **Decoding delay**: Local device performance * **Display delay**: Frame buffering based on delay setting ### Audio Issues If audio is choppy or out of sync: 1. **Audio typically follows video delay settings** 2. **If audio lags behind video**: Increase delay control 3. **If audio stutters**: Reduce bitrate to lower network load 4. **If no audio**: Check that audio streaming is supported on target device ## Server-Side Issues ### Server Jar Not Found If the server keeps re-uploading: ```bash theme={null} # Check if server exists and is valid adb -s :5555 shell ls -alh /data/local/tmp/scrcpy-server.jar # Should show file size around 40-50KB ``` **If file is missing or corrupted:** * Clear app data on local device * Reinstall Scrcpy for Android * Manually push server jar if needed ### Port Forwarding Failures **Error symptoms:** * Connection hangs at "Connecting…" * Socket connection fails repeatedly **Check port forwarding:** ```bash theme={null} # Verify forwarding is active adb forward --list # Should show: tcp:7008 tcp:7007 # Remove all forwards and retry adb forward --remove-all ``` The app forwards local port 7008 to remote port 7007 automatically during connection setup. ## Debugging Tips ### Enable Detailed Logging Monitor logcat for detailed error messages: ```bash theme={null} # Filter for Scrcpy logs adb logcat | grep -i scrcpy # Look for connection errors adb logcat | grep -i "connection\|error\|fail" ``` ### Common Log Messages | Log Message | Meaning | Action | | ---------------------------------- | -------------------- | ---------------------- | | "Connecting to 127.0.0.1 success" | Socket connected | Normal | | "can't read socket Resolution" | Handshake timeout | Check server execution | | "attempts--" | Retry attempt | Wait or troubleshoot | | "Connection Timed out 2" | Connection failed | Check network/ADB | | "Network OR ADB connection failed" | Initial setup failed | Verify ADB access | ### Manual Connection Test Test the connection manually to isolate issues: ```bash theme={null} # 1. Connect via ADB adb connect :5555 # 2. Verify connection adb devices # Should list your device # 3. Test file push adb -s :5555 push test.txt /data/local/tmp/ # 4. Test port forwarding adb -s :5555 forward tcp:7008 tcp:7007 # If any step fails, that's where the problem lies ``` ## Getting Help If you're still experiencing issues: Review connection requirements and process Ensure settings are appropriate for your network Verify control functionality works correctly Collect logs and report bugs to the development team When reporting issues, include: device models, Android versions, network type (Wi-Fi/LTE), resolution/bitrate settings, and relevant log excerpts.