Connect & Get help from fellow developers on our Discord community.

Debug common SDK errors

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

This page describes common error codes you might encounter when using the BrowserStack SDK and provides troubleshooting steps to resolve them. Each error code includes specific actions you can take to fix the issue.

Debug Config Error

The SDK Debug Utility helps you troubleshoot issues in your system and project configuration, if any.

Installation

Download the debug utility CLI binary for your operating system from the following links:

OS family	x64 variant	arm64 variant
macOS	macOS x64	macOS arm64
Windows	Windows	—
Linux	Linux x64	Linux arm64
Alpine Linux	Alpine x64	Alpine arm64

How to use the debug utility

Extract the downloaded .zip file.
Open your terminal (Command Prompt, PowerShell, or Terminal depending on your OS).

To invoke the debug utility, execute the following command:

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

CLI options

The following table describes the available CLI options for the debug utility:

Option	Description
`-p, --project-directory <dir path>`	Project directory path overriding the default current working directory.
`-u, --username <username>`	BrowserStack username. You can also set the environment variable `BROWSERSTACK_USERNAME`. This information is available on your Profile page.
`-k, --key <access key>`	BrowserStack access key. You can also set the environment variable `BROWSERSTACK_ACCESS_KEY`. This information is available on your Profile page.
`-l, --language <value>`	Specify the language of the SDK you are using. Examples: `java`, `python`, `node`, `csharp`, `ruby`, `php`.
`-h, --help`	Display help for the command (equivalent to `debug -h`).

Common SDK errors

The following sections list the most common SDK error codes and their recommended troubleshooting steps:

SDK-TRA-001

Integrate a supported test framework if you intend to use features such as Test Reporting & Analytics (TRA), Accessibility, App Accessibility, or Percy.
If a test framework is already in use, specify it explicitly under the framework key in your browserstack.yml file.
If the issue persists, contact BrowserStack support.

SDK-TRA-002

Review the error message for this error code to confirm the list of currently supported test frameworks.
If your intended framework is supported as per documentation, verify that the framework key in your browserstack.yml file is correctly spelled and matches the supported value.
If your framework is unsupported or not listed in documentation, contact BrowserStack support for clarification or feature requests.

SDK-TRA-003

Check for the process signal code you received in the table below:

Signal	Number	Typical cause	Default action	Notes / causality
SIGINT	2	User interrupts the process (usually by pressing Ctrl + C in the terminal).	Terminate process	Sent by the terminal driver; intended for graceful shutdown on user request.
SIGTERM	15	Generic termination request (usually from `kill <pid>` without `-9`).	Terminate process	Standard way to ask a process to exit cleanly. Used by systemd, Docker, Kubernetes, etc.
SIGHUP	1	Hangup—controlling terminal or session is closed (user logs out, terminal disconnects).	Terminate process	Historically meant “modem hangup”; daemons often repurpose this for “reload config.”
SIGABRT	6	Process calls abort (for example, due to assertion failure or runtime library abort).	Core dump	Indicates abnormal termination due to internal error—often signals a bug or failed invariant.

SDK-TRA-004

Ensure you have installed the cucumber-core dependency with your test project.
Another way to check if the dependency is installed is by running this command: mvn dependency:tree
If the dependency is installed and you continue to see this error code alongside missing tests on the BrowserStack dashboard, contact BrowserStack support.

SDK-TRA-005

Review the error message for this code to check the list of supported Cucumber versions.
If you’re using an unsupported version, upgrade or downgrade to a supported one.
If you’re already running a supported version or the migration is not feasible, contact BrowserStack support.

SDK-TRA-006

Check if your test framework recently updated, try reverting to an earlier version to confirm if a breaking change caused the issue.
Verify that your test library is correctly installed by running this command: mvn dependency:tree
Compare your project’s dependencies with BrowserStack’s public sample projects.
Re-verify that the correct framework value is defined in your browserstack.yml.
If there have been no recent dependency changes and the issue persists, contact BrowserStack support.

Did this page help you?

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!