Connect & Get help from fellow developers on our Discord community.
Ask the Community
Ask the Community
Troubleshooting device tunneling
Find solutions to common issues you might encounter while using device tunneling.
Common issues
| Issue | Description / Cause | Solution |
|---|---|---|
| Permission Denied | Occurs during iOS setup when administrator privileges are lacking. | Ensure you have admin rights and have provided the system password. See the iOS Setup Guide. |
| Port Conflicts | The orchestrator fails to start because default ports (8080, 7005+) are already in use. |
Check for other applications using these ports. You can change the default ports in the Advanced configuration. |
| Connection Timeouts | Your network, firewall, or proxy is blocking the connection to BrowserStack’s servers. | Verify your network connectivity and check your firewall or proxy settings to ensure they are not blocking the connection. |
| Command Not Responding | An adb or idevice_* command hangs and becomes unresponsive. |
Android: Run adb disconnect and then reconnect using adb connect localhost:<port>. Both: Restart the tunnel connection using the device-tunnel disconnect and device-tunnel connect commands. |
Android device appears unauthorized |
When you run adb devices, the device is listed as unauthorized because the USB debugging prompt wasn’t accepted. |
1. Go to your App Automate dashboard and open the interactive session. 2. On the device screen, find the “Allow USB debugging?” pop-up and click “Allow”. 3. Run adb devices on your local machine again; the status should now be device. |
For more detailed debugging, you can inspect the log files generated by the tool. They are located in your home directory: ~/.browserstack/device-tunnel/logs/
Related topics
- Device tunneling overview - Understand the benefits and prerequisites of device tunneling.
- Getting started - Install the tool and run your first tunnel.
- iOS setup guide - Configure your macOS environment for iOS device tunneling.
- CLI reference & management - Explore command-line options for managing device tunnels
- Advanced configuration - Customize tunnel settings for performance and security.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!