Debug common SDK errors

Learn how to identify and fix frequent SDK integration and runtime errors on BrowserStack Automate with actionable troubleshooting steps.

This page lists common BrowserStack SDK errors and how to fix them. Use it to quickly identify configuration, dependency, or environment issues and restore test stability.

Debug config errors

Use the SDK Debug Utility to verify local system and project configuration (credentials, directory structure, language selection, connectivity) before you run a large test suite.

Installation

Download the debug utility CLI binary for your operating system:

Run the debug utility

To run the utility:

1. Extract the downloaded .zip file.
2. Open your terminal (Command Prompt, PowerShell, or Terminal depending on your OS).
3. To invoke the debug utility, execute the following command:

./binary-[OS-Variant] debug -u <username> -k <accesskey> -p <project-directory> -l <language>

Replace the OS variant above from the command.

Example

./binary-macos-arm64 debug -u <username> -k <accesskey> -p <project-directory> -l <language>

CLI options

The following table lists available CLI options:

Test reporting and analytics errors

These errors affect reporting, analytics, or test visibility on the dashboard.

Missing tests on dashboard

If tests run but do not appear on the BrowserStack dashboard, you likely have a configuration or dependency issue.

Cause 1: Framework Configuration SDK-TRA-001 SDK-TRA-002

Your browserstack.yml file is missing the framework key or its value is incorrect or unsupported.

Resolution

• Ensure you have integrated a supported test framework and have explicitly defined the correct, supported framework name (check for spelling) under the framework key in your browserstack.yml file.

Cause 2: Cucumber Dependency Issues SDK-TRA-004 SDK-TRA-005

You are missing a required Cucumber dependency or using an unsupported version.

Resolution

• Ensure you have installed the cucumber-core dependency using the command mvn dependency:tree.
• Verify you are using a Cucumber version supported by BrowserStack and upgrade or downgrade your project’s version as needed.

Cause 3: General Dependency/Configuration Issue SDK-TRA-006

This error can occur if a recent update broke the integration or if dependencies are installed incorrectly.

Resolution

• Check if your test framework was recently updated; try reverting to a known-working earlier version to isolate the issue and report it to BrowserStack support.
• Verify all test libraries are correctly installed (e.g., mvn dependency:tree) and then compare your project’s dependencies with BrowserStack’s public sample projects.

Test process terminates unexpectedly SDK-TRA-003

The test process stopped due to an external signal (for example, Ctrl + C or kill), not an SDK failure.

Resolution Check the process signal code you received against this table to understand the external cause:

App accessibility errors

These errors occur during app accessibility testing when the app binary is not configured correctly.

Report Generation failures on App Accessibility

This single resolution applies if you experience any of the following issues:

Resolution

• For app-based test execution, the SDK requires a path or URL to your app. You must define the app key in your configuration.
• If using WebdriverIO with BrowserStack Plugin, add the app key inside the browserstack service block in your wdio.conf.js:

  services: [
  ['browserstack', {
    // ... other options
    app: '/path/to/local/app.apk'
    // OR
    app: 'bs://<app-id>'
  }]
  ]
  

If you use the BrowserStack SDK, add one of the following to browserstack.yml:

userName: YOUR_BROWSERSTACK_USERNAME
accessKey: YOUR_BROWSERSTACK_ACCESS_KEY
## .... your configurations
app: /path/to/local/app.apk # SDK will upload your app
## OR
app: bs://<app-id>

Cause 1: Missing app key

Resolution For app-based test execution, the SDK requires a path or URL to your app. You must define the app key in your configuration.

• If you are using WebdriverIO with BrowserStack Plugin for various products and features it provides and have App based setup, make sure you add ‘app’ key inside the ‘browserstack’ service block:

services: [
['browserstack', {
app: '/path/to/local/app.apk'
// OR
app: 'bs://<app-id>'
}]
]

• If you leverage BrowserStack SDK to enhance your testing outcomes, make the following change in your browserstack.yml file:

userName: YOUR_BROWSERSTACK_USERNAME
accessKey: YOUR_BROWSERSTACK_ACCESS_KEY
## .... your configurations
app: /path/to/local/app.apk # SDK will magically upload your apps, no more manual efforts
## OR
app: bs://<app-id>