Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
118 lines (76 loc) · 4.09 KB

TROUBLESHOOTING.md

File metadata and controls

118 lines (76 loc) · 4.09 KB
Raw

Troubleshooting

Device Not Detected

Symptom: No device appears in the device dropdown after connecting via USB.

  1. Ensure USB Debugging is enabled on the device:
    • Settings → About Phone → tap Build Number 7 times
    • Settings → Developer Options → enable USB Debugging
  2. Accept the "Allow USB Debugging" prompt on your device screen
  3. Try a different USB cable or port (some cables are charge-only)
  4. Run adb devices in a terminal to verify ADB sees the device
  5. On Windows, install the manufacturer's USB driver or Google USB Driver

scrcpy Not Found / Path Error

Symptom: Error about scrcpy not being found when clicking Run.

  • Go to Settings and set the scrcpy directory to the folder containing the scrcpy executable
  • Verify scrcpy works independently: open a terminal and run scrcpy --version
  • If installed via package manager, the directory may already be on PATH — leave the setting blank to use PATH

ADB Not Found

Symptom: Devices never appear; logs show ADB errors.

  • scrcpy bundles adb — ensure the scrcpy directory is set correctly in Settings
  • If using a system-installed ADB, ensure it's on PATH
  • On Windows, check that no other ADB version conflict exists (adb kill-server && adb start-server)

Wireless Connection Fails

Symptom: "Connect Wirelessly" button fails or device disconnects immediately.

  1. Ensure device and computer are on the same WiFi network
  2. Complete the initial USB connection step before switching to wireless
  3. Check if a firewall is blocking port 5555 (default ADB TCP port)
  4. Try manually: adb tcpip 5555 then adb connect <device-ip>:5555
  5. On Android 11+, use the Wireless Debugging option in Developer Options instead

Black Screen / No Video

Symptom: scrcpy window opens but shows a black screen.

  • Some apps block screen capture (banking apps, Netflix, etc.) — this is a device restriction
  • Try disabling Secure Flag in Advanced settings if the target app allows it
  • Check if the device screen is on and unlocked
  • Try lowering the video bitrate or resolution in Common Commands panel

Audio Not Working

Symptom: No audio is forwarded from the device.

  • Audio forwarding requires Android 11 or higher
  • Ensure no audio is playing through the device speaker (some devices block capture when nothing is playing)
  • Check the Audio Commands panel — try switching the audio codec or source
  • Run with --no-audio flag first to confirm the issue is audio-specific

App Crashes on Launch

Symptom: Scrcpy GUI closes immediately or shows an error on startup.

  • Check the logs file if file logging is enabled (Settings → Enable File Logging)
  • Delete the settings file and restart to reset to defaults:
    • Windows: %APPDATA%\scrcpy_gui\settings.json
    • macOS: ~/Library/Application Support/scrcpy_gui/settings.json
    • Linux: ~/.config/scrcpy_gui/settings.json

Recordings Not Saving

Symptom: Recording completes but no file is found.

  • Set the Recordings directory in Settings to a valid writable path
  • Ensure sufficient disk space is available
  • Check the filename — if a file with the same name already exists it may be overwritten silently

Scripts/BAT Files Tab Not Visible

Symptom: The Scripts tab is missing from the sidebar.

  • Go to Settings → enable Show Scripts Tab
  • Set the Scripts directory to the folder where your .bat / .sh / .command files are stored

High CPU / Lag

Symptom: scrcpy or the host machine runs slowly during mirroring.

  • Lower the video resolution: --max-size 1024
  • Lower the bitrate: --video-bit-rate 4M
  • Switch to a hardware encoder in the Audio/Video panels if available for your device
  • Use a wired USB connection instead of wireless for lower latency

Still Stuck?

Open an issue at GitHub Issues and include:

  • Your OS and version
  • scrcpy version (scrcpy --version)
  • The error message or log output (Settings → Enable Logging → copy from Logs tab)