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.

Cause 4: Unexpected Internal Error SDK-TRA-007

Some test details could not be captured or reported to the BrowserStack Test Reporting & Analytics (TRA) dashboard due to an unexpected internal error.

Resolution

• Re-run your test suite to check if the issue reproduces consistently.
• Ensure that your SDK version is up to date.
• Confirm there were no abrupt process terminations (e.g., SIGINT, SIGTERM) during the run.
• If the issue persists, please contact BrowserStack Support for further investigation.

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>'
  }]
  ]
  

• 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://'
    }]
    ]
  

• There are more ways to configure your app, refer to WebdriverIO service documentation.
• 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://
  

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>

SDK Generic Errors

Cause 1: Access restricted to .browserstack folder SDK-GEN-001

The BrowserStack SDK could not access or read files within the .browserstack directory located in the user’s home directory. This folder stores essential session, cache, and state information required for proper functionality.

Resolution

• Ensure the .browserstack folder exists in your home directory. If missing, the SDK will recreate it once permissions are fixed.
• Fix read/write permissions:
  • Linux/macOS: chmod -R 755 ~/.browserstack
  • Windows: Check Properties → Security
• If permissions look correct but access failures continue, contact BrowserStack Support.

Cause 2: Connection Restricted to BrowserStack SDK-GEN-002

The BrowserStack SDK could not communicate with BrowserStack cloud services because of network connectivity issues. This may be due to internet outages, blocked outgoing requests, VPN/proxy misconfigurations, or corporate firewall restrictions.

Resolution

• Confirm your internet connection and re-run the tests. If using a corporate VPN or firewall, ensure outbound access to *.browserstack.com is allowed.
• Validate proxy settings. Incorrect proxy configuration commonly blocks SDK requests.
• Try running the tests on a non-corporate or alternate network to isolate environment issues.
• If connectivity appears normal but failures continue, contact BrowserStack Support.

Relevant documentation:

• Run tests behind proxy
• Configure proxy settings

Cause 3: SSL Certification Error SDK-GEN-003

The BrowserStack SDK encountered an SSL certificate validation error while establishing a secure connection to BrowserStack cloud services. This often occurs due to incorrect system time, outdated root certificates, or SSL interception by corporate proxies.

Resolution

• Verify system date, time, and timezone—SSL fails if the clock is inaccurate.
• Update system root certificates:
  • Linux: Update CA certificates using your package manager
  • macOS: Ensure latest system updates are installed
  • Windows: Run Windows Update to refresh trusted certificates
• If using a corporate proxy performing SSL inspection, ensure the proxy’s root CA certificate is correctly installed on your machine.
• Re-run the tests after applying corrections.

Cause 4: Environment Variable conflict SDK-GEN-004

The BrowserStack SDK detected user-defined environment variables that conflict with internal environment variables used by the SDK. This can lead to unexpected behavior or incorrect test reporting.

Resolution

• Review the environment variable(s) listed in the error message.
• Rename or remove these variables from your shell, CI environment, or application configuration.
• If you rely on these variable names, choose alternative names to avoid collision with SDK-reserved variables. After updating environment variables, restart your terminal or CI job to ensure the changes propagate.
• If you need help identifying a safe naming convention, reach out to BrowserStack Support.