Troubleshooting

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.

Possible Causes

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

Solutions

Verify the target device IP address is correct
Ensure both devices are on the same network
Check that wireless debugging is enabled on the target
Try pinging the target device IP from a terminal
Restart wireless debugging on the target device
Keep target device screen on during connection

# From a terminal on your local device
ping 192.168.0.73

# If ping fails, devices cannot communicate

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:

Manually verify server jar exists on target:

adb -s <ip>:5555 shell ls -alh /data/local/tmp/scrcpy-server.jar

Check server execution permissions
Clear /data/local/tmp/ and retry connection
Restart ADB server on both devices

ADB Connection Issues

”Network OR ADB connection failed”

This message indicates the ADB connection or server upload failed.

Network Issues
ADB Issues
Permission Issues

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

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:

Check your delay control setting (try “High (100ms)”)
Monitor Wi-Fi signal strength
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

// 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

Orientation Mismatch

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

Surface Not Ready

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

Decoder Configuration Issues

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:

Press back button twice to disconnect
App returns to main screen
Wait for orientation to stabilize to portrait
Reconnect

Performance Optimization

Improving Frame Rate

Optimize Resolution

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

Adjust Bitrate

Match bitrate to network capacity:

Test with 2 Mbps first
Increase to 4 Mbps if stable
Use 6 Mbps only on excellent local networks

Set Appropriate Delay

Balance responsiveness vs. smoothness:

Low (30ms): Fast networks, prioritizes responsiveness
Medium (60ms): Default, good balance
High (100ms): Slow networks, prioritizes smooth playback

Close Background Apps

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:

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:

Audio typically follows video delay settings
If audio lags behind video: Increase delay control
If audio stutters: Reduce bitrate to lower network load
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:

# Check if server exists and is valid
adb -s <ip>: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:

# Verify forwarding is active
adb forward --list

# Should show: <serial> 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:

# 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:

# 1. Connect via ADB
adb connect <ip>:5555

# 2. Verify connection
adb devices
# Should list your device

# 3. Test file push
adb -s <ip>:5555 push test.txt /data/local/tmp/

# 4. Test port forwarding
adb -s <ip>:5555 forward tcp:7008 tcp:7007

# If any step fails, that's where the problem lies

Getting Help

If you’re still experiencing issues:

Check Connection Setup

Review connection requirements and process

Review Configuration

Ensure settings are appropriate for your network

Test Control Features

Verify control functionality works correctly

Report Issues

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.

Get Started

User Guide

Advanced

Overview

Connection Timeout Errors

”Connection Timed out 2”

Connection Timeout During Handshake

ADB Connection Issues

”Network OR ADB connection failed”

Repeated Connection Failures

Network Problems

High Latency

Packet Loss

Black Screen Issues

Screen Stays Black After Connection

Black Screen After Rotation

Performance Optimization

Improving Frame Rate

Reducing Latency

Audio Issues

Server-Side Issues

Server Jar Not Found

Port Forwarding Failures

Debugging Tips

Enable Detailed Logging

Common Log Messages

Manual Connection Test

Getting Help

Check Connection Setup

Review Configuration

Test Control Features

Report Issues

Build docs developers (and LLMs) love

Get Started

User Guide

Advanced

​Overview

​Connection Timeout Errors

​”Connection Timed out 2”

​Connection Timeout During Handshake

​ADB Connection Issues

​”Network OR ADB connection failed”

​Repeated Connection Failures

​Network Problems

​High Latency

​Packet Loss

​Black Screen Issues

​Screen Stays Black After Connection

​Black Screen After Rotation

​Performance Optimization

​Improving Frame Rate

​Reducing Latency

​Audio Issues

​Server-Side Issues

​Server Jar Not Found

​Port Forwarding Failures

​Debugging Tips

​Enable Detailed Logging

​Common Log Messages

​Manual Connection Test

​Getting Help

Check Connection Setup

Review Configuration

Test Control Features

Report Issues

Build docs developers (and LLMs) love

Overview

Connection Timeout Errors

”Connection Timed out 2”

Connection Timeout During Handshake

ADB Connection Issues

”Network OR ADB connection failed”

Repeated Connection Failures

Network Problems

High Latency

Packet Loss

Black Screen Issues

Screen Stays Black After Connection

Black Screen After Rotation

Performance Optimization

Improving Frame Rate

Reducing Latency

Audio Issues

Server-Side Issues

Server Jar Not Found

Port Forwarding Failures

Debugging Tips

Enable Detailed Logging

Common Log Messages

Manual Connection Test

Getting Help