Skip to main content

​
Installation Issues

​
Cannot Install APK

Problem: Installation fails or is blocked Solutions:
  1. Enable “Install unknown apps” for your browser/file manager
  2. Check available storage space (need at least 100MB)
  3. Verify Android version is 7.0 or higher
  4. Try installing from Desktop application instead

​
Installation Succeeded but App Won’t Open

Solutions:
  1. Restart your device
  2. Clear app cache from Settings > Apps
  3. Reinstall the app
  4. Check for Android system updates

​
Permission Issues

​
Accessibility Service Keeps Disabling

Solutions:
  1. Disable battery optimization for Qaptly Pilot
  2. Add app to “Protected apps” (if available on your device)
  3. Check for MIUI/OneUI/other custom ROM restrictions
  4. Grant all requested permissions

​
”Display Over Other Apps” Permission Not Working

Solutions:
  1. Manually enable in Settings > Apps > Qaptly Pilot
  2. Restart the app after enabling
  3. Check for conflicting overlay apps
  4. Try disabling other overlay permissions temporarily

​
Connection Issues

​
Device Not Appearing in Desktop

Solutions:
  1. Verify USB debugging is enabled
  2. Check USB cable connection
  3. Try a different USB port
  4. Run adb devices in terminal to verify ADB connection
  5. Revoke and re-authorize USB debugging

​
Connection Drops During Testing

Solutions:
  1. Use a high-quality USB cable
  2. Disable USB power saving on device
  3. Keep device screen on during testing
  4. Check for loose USB connections

​
Test Execution Issues

​
Tests Not Starting

Solutions:
  1. Verify all permissions are granted
  2. Check Qaptly Pilot service is running
  3. Restart the app
  4. Reconnect from Desktop application

​
Tests Fail Randomly

Solutions:
  1. Disable background app optimization
  2. Turn off battery saver mode
  3. Close unnecessary background apps
  4. Increase wait times in test steps

​
UI Elements Not Being Found

Solutions:
  1. Verify Accessibility Service is enabled
  2. Check app has focus during test
  3. Increase element detection timeout
  4. Update element locators if app UI changed

​
Command Execution Invalid

Solutions:
  1. Go to Settings -> Pilots to adjust settings
  2. Try switching between Accessibility or ADB modes
Switching Input Method

​
Text Input Issues

Solutions:
  1. Switch to the built-in Qaptly IME from Qaptly Auto for Android
Switching Input Method

​
Performance Issues

​
App Runs Slowly

Solutions:
  1. Clear app cache
  2. Restart device
  3. Close background apps
  4. Check available storage space
  5. Reduce screen resolution if possible

​
High Battery Drain

Solutions:
  1. Keep device plugged in during testing
  2. Reduce screen brightness
  3. Disable unnecessary connectivity (WiFi, Bluetooth)
  4. Close unused apps

​
Error Messages

​
”Service Not Running”

Cause: Qaptly Pilot background service has stopped Solutions:
  1. Reopen the app
  2. Re-enable Accessibility Service
  3. Restart device
  4. Reinstall if issue persists

​
”Permission Denied”

Cause: Required permissions not granted Solutions:
  1. Review Setup & Permissions
  2. Grant all required permissions
  3. Restart app after granting permissions

​
”Connection Lost”

Cause: USB connection interrupted Solutions:
  1. Check physical USB connection
  2. Verify USB debugging is still enabled
  3. Reconnect device
  4. Try different USB cable/port

​
Device-Specific Issues

​
Samsung Devices

  • May need to disable “Optimize battery usage”
  • Check Knox security settings
  • Enable “Install unknown apps” in settings

​
Xiaomi/MIUI Devices

  • Add to “Autostart” apps
  • Disable battery optimization
  • Enable “Display pop-up windows” permission

​
Huawei Devices

  • Add to “Protected apps”
  • Disable “Close apps after screen lock”
  • Enable all app permissions

​
Getting Help

If you continue experiencing issues:
  1. Check the app version and update if available
  2. Review the Usage Guide
  3. Contact your administrator
  4. Provide error logs if available
Related: