No Result Found
Get your setup working faster. Join our Discord for optimisation tips from elite testers. Join our DiscordJoin our Discord

Troubleshoot Device Tunnel CLI issues

Troubleshooting common issues with Device Tunnel and following best practices

Use this reference to diagnose and resolve common Device Tunnel CLI issues and follow best practices. Each entry includes the error symptom, root cause, and resolution steps.

Troubleshooting guide

Issue Symptom Cause Resolution
Orchestrator not running Error: Device Tunnel Orchestrator is not running. Orchestrator process is not running or status file is stale 1. Check process: ./binary-macos-arm64 device-tunnel status
2. Start it: ./binary-macos-arm64 device-tunnel start --username <user> --access-key <key>
3. If status shows running but connect fails, run stop then start
Orchestrator already running Orchestrator is already running! PID: 12345 Port: 8080 Orchestrator instance already active Run ./binary-macos-arm64 device-tunnel stop then ./binary-macos-arm64 device-tunnel start --username <user> --access-key <key>
Device not found Error: Device ID “UNKNOWN123” not found in your dedicated devices. • Typo in UDID
• Device not in dedicated fleet
• Device allocated to another user		 Run ./binary-macos-arm64 device-tunnel devices to list devices. Wait for device status to become available or contact support
Device name ambiguity Error: Device “Pixel 7 Pro-13.0” exists on multiple platforms: android, ios. Same device name exists on both platforms Add --platform android or --platform ios flag: ./binary-macos-arm64 device-tunnel connect --device-name "Pixel 7 Pro-13.0" --platform android
Tunnel stuck in PENDING TUNNEL REQUEST ACCEPTED (PENDING) and no active tunnel after several minutes • Network connectivity issue
• Firewall blocking port 8080
• Orchestrator killed after API call		 1. Verify port 8080 is open
2. Check orchestrator: ./binary-macos-arm64 device-tunnel status
3. Retry: ./binary-macos-arm64 device-tunnel connect --device-id <UDID> --new-connection
4. Check orchestrator logs
ADB device not showing (Android) connect succeeds but adb devices doesn’t show device ADB not connected to tunnel port Manually connect: adb connect localhost:<localPort> then verify with adb devices. If fails: ensure adb in $PATH, kill existing server: adb kill-server && adb start-server, check port binding: lsof -i :<localPort>
Authentication failures (401) Error: Authentication failed. Check your username and access key. Invalid credentials 1. Verify at profile page
2. Check for whitespace in environment variables
3. Verify browserstack_username and browserstack_accesskey in config file
Access denied (403) Error: Access denied. Your account may not have Device Tunnel access. Account lacks Bridge Cloud subscription Contact BrowserStack support
BrowserStack Local conflict BrowserStack Local instances are already running! Existing BrowserStack Local process detected 1. Kill processes: pkill BrowserStackLocal
2. Or disconnect from dashboard
3. Retry start
Multiple sessions for device Error: Multiple running sessions found for “Galaxy S24-14.0”. Multiple active sessions with same device name Use --device-id instead of device name. Run devices to identify UDID
Partial multi-device failure Some devices connect, others fail. Non-zero exit code Device-specific connection issues 1. Check stderr for error messages
2. Re-run connect for failed devices
3. Verify failed devices are available
Request timeout Error: Request timed out after waiting for device allocation. • Device not in available state
• 2-hour session limit reached
• Device in cleanup phase		 1. Check device status is “available”
2. Wait 10 to 15 minutes for cleanup to complete
3. Retry on different device
4. Contact support if device stuck in cleanup

A device also enters the cleanup phase when you manually stop a tunnel with the stop command, or when an error occurs mid-tunnel, not only when the 2-hour maximum duration for a continuous device block is reached. This behavior is consistent with real device sessions on App Automate. Cleanup typically takes 10 to 15 minutes. Before you retry a tunnel connection, verify the device shows available in the devices output, and contact BrowserStack support if a device goes offline or stays stuck in cleanup for longer than that.

Best practices

Follow these best practices to get the most out of Device Tunnel CLI.

Device identification

Always use --device-id over --device-name when you know the UDID. It is deterministic, enables auto-reconnect, and avoids ambiguity errors.

Session management

  • Use disconnect between test phases, not stop, if you want to preserve device state. The session and device allocation stay alive across disconnect and connect cycles.
  • Use stop only when fully done with a device. It frees the device back to the pool, which may make it unavailable if another user picks it up.
  • Use --new-connection sparingly. Creating a new session adds latency from build, session provisioning, and polling. Only use it when you genuinely need a fresh device state.

Monitoring and testing

  • Monitor with list-tunnels in CI to verify tunnels are live before running tests:
Copy icon Copy
  • For parallel test suites, pre-connect all devices at the start of the suite, run all tests, then disconnect all at the end, instead of connecting or disconnecting per test.

Orchestrator management

Keep the orchestrator running for the entire test session. Stopping the orchestrator terminates all tunnels and cleans up all sessions.

Session duration

For sessions longer than 3 to 4 hours, be aware of potential hardware overheating on the physical device. Consider breaking long runs into shorter segments with device resets between.

Logging and diagnostics

Capture logs explicitly. This is a direct-access solution. BrowserStack does not automatically store logs, video, or network traffic. Use your own tooling to capture these.

CI/CD integration

Use --json in CI pipelines to parse results reliably without depending on text formatting.

Error codes reference

When using --json mode, errors include a code field for programmatic handling. Use these codes to implement retry logic or specific error handling in your automation.

Error Code Description Common Causes Resolution
AUTH_FAILED Authentication failed Invalid username or access key, no credentials stored on the orchestrator Verify your username and access key in your config file or environment variables
ACCESS_DENIED Account lacks the required subscription Account doesn’t have a Bridge Cloud or Device Tunnel subscription Contact BrowserStack support to verify your account permissions
NOT_FOUND Device, session, or resource not found Invalid device ID, session already stopped, device not in your dedicated fleet Verify the device ID with the devices command, and check session status with sessions
CONFLICT Resource already exists A tunnel is already active for the device Run list-tunnels to check existing tunnels before retrying
RATE_LIMITED Too many API requests Excessive command or API call frequency Wait before retrying, and reduce request frequency in CI scripts
SERVICE_UNAVAILABLE BrowserStack service unavailable API downtime, 5xx response, maintenance window Retry after a delay, and check the BrowserStack status page
NETWORK_TIMEOUT Operation timed out Device provisioning timeout, network latency, slow response Retry the operation, and check your network connectivity
NETWORK_ERROR General network failure Connectivity issue between your machine and BrowserStack Check your network connection and firewall settings, then retry
INVALID_ARGS Invalid command argument or flag Malformed device ID, both --device-id and --device-name provided, ambiguous --device-name across platforms Verify command syntax, and check for mutually exclusive or missing flags
UNKNOWN_COMMAND Command not recognized Typo in the command name or an unsupported command Run device-tunnel --help to see the list of supported commands
PARTIAL_FAILURE Some devices succeeded, some failed in a multi-device operation Mixed success and failure in a batch connect, disconnect, or stop operation Check the failed array in the JSON response for device-specific errors
UNEXPECTED Unhandled exception Orchestrator not running, or an unanticipated internal error Run status to confirm the orchestrator is running, then check logs and retry

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

Is this page helping you?

Yes
No

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!

Talk to an Expert
Download Copy Check Circle