Edge cases and advanced behavior

Edge cases and advanced command behavior for Device Tunnel CLI

This section covers edge cases and advanced command behavior to help you troubleshoot unexpected scenarios.

Device name ambiguity

If a device model exists on both Android and iOS (for example, hypothetical cross-platform device list):

Solution: Always add --platform android or --platform ios when using --device-name.

Multiple sessions for the same device name

If your account has two running sessions for the same device name (for example, two instances of “Pixel 7 Pro-13.0”):

Solution: Use --device-id to be explicit.

Tunnel pending state

When connect returns TUNNEL REQUEST ACCEPTED (PENDING), the localPort is not yet bound. This means:

• The API has accepted the tunnel request.
• The platform (BrowserStack) has not yet established the local socket.

Use list-tunnels to poll until the tunnel shows active:

ADB auto-connect

For Android devices, when localPort is available at connect time, the CLI automatically runs:

This is best-effort. If adb is not found, a warning is logged and the tunnel itself is still usable. ADB is only needed if you are running native ADB commands or using automation tools that require ADB connectivity.

iOS WDA port

For iOS devices, the wdaPort is displayed in the tunnel output. Point your WebDriver client at localhost:<wdaPort> for WebDriverAgent-based automation.

Comma-separated identifiers

Both --device-id and --device-name accept comma-separated lists:

Leading and trailing whitespace around commas is stripped automatically.

Partial failures in multi-device commands

When connecting or disconnecting multiple devices, each device is processed independently. If device 1 fails and device 2 succeeds:

• Text mode: Errors are printed to stderr, succeeded devices print disconnect hints to stdout.
• JSON mode: Envelope contains both succeeded and failed arrays, with success: false.
• CLI exit code: Non-zero if any device failed.

--new-connection flag

When --new-connection stops an existing session before creating a new one, a failure during that stop is logged as a debug message and does not block the new session creation.

JSON output mode

All commands support --json flag for programmatic and CI use. Output is always a clean JSON envelope on stdout.

Success envelope

Error envelope

Partial failure envelope (multi-device)

Error codes

The code field in the error and partial-failure envelopes is always one of the following: