Perform Line-by-Line Debugging with Vega Studio

Learn how to debug Vega apps and Turbo Modules with Vega Studio through GDB (GNU Debugger). Vega Studio provides built-in debugging capabilities that use GDB for native code debugging, allowing you to inspect running programs, set breakpoints, and step through code execution. Turbo Modules are native code components that extend React Native functionality. For Chrome DevTools debugging, see Use Chrome DevTools for App Profiling.

Prerequisites

Before you can debug apps with Vega Studio, complete these setup requirements to ensure your development environment and target devices are properly configured.

(Optional) Review the VS Code debugging documentation.
(Optional) Learn about GDB (GNU Debugger).
Choose your debugging target: Vega Virtual Device or Fire TV Stick.
Enable developer mode for your target: Vega Virtual Device
1. Open VS Code.
2. Select the Vega Studio extension icon from the activity bar.
3. Navigate to Devices.
4. Start the Vega Virtual Device.
5. Open a terminal and run:
kepler exec vda shell vsm developer-mode enable
Fire TV Stick
1. Connect your Fire TV Stick to your development machine through USB.
2. Enable developer mode following Run your app on Fire TV Stick.

Configure the Vega Studio debugger

Set up debugging configurations to specify how Vega Studio should launch and connect to your app. You can use automatic configuration for quick setup or manual configuration for custom debugging scenarios.

Automatic configuration

Open your project file or select it from the sidebar.
Choose Run and Debug from the VS Code activity bar.
Select the debugger type:
- Vega: For React Native for Vega apps (JavaScript/TypeScript code)
- Vega Native: For Turbo Modules (native C++ code)
The debugger attaches to the running app.
Follow the steps in Debug your app.

Manual configuration

Go to Run and Debug in the VS Code activity bar.
Click create a launch.json file.
Select a project from the prompt (skip if you only have one project).
Select the debugger type:
- Vega: For React Native for Vega apps (JavaScript/TypeScript code)
- Vega Native: For Turbo Modules (native C++ code)

Vega Studio creates a launch.json file with default configuration.

Specify your target device

When multiple devices are connected, specify your target device by setting the deviceId property:

"${command:kepler.state.getSelectedDeviceId}" - Uses device selected from the sidebar
"KeplerVirtualDevice" - Targets Vega Virtual Device specifically
Device serial ID - Targets specific physical device

Add configuration to launch.json

To add additional configurations to an existing launch.json file:

Open your app’s launch.json file.
Select the Add Configuration button.
Choose your desired launch target from the available options.
Save your changes.

Set up breakpoints

Create breakpoints in your app by clicking in the left margin of the code editor next to line numbers. Screenshot showing the setting of a breakpoint in the VS Code editor.

Screenshot showing the setting of a breakpoint in the VS Code editor.

Launch.json attributes

Attribute	Description
type	Debugger type: “kepler” (React Native) or “keplerNative” (Turbo Modules)
request	Request type: “launch” (start new session) or “attach” (connect to running app)
name	Display name in debug dropdown
keplerMode	Debug mode: “debug” or “release”
cwd	Workspace directory
deviceId	Target device identifier
forceRebuild	Auto-rebuild before launch (default: false)
disableAppTimeout	Controls ANR timeout behavior during debugging. When `true` (default), disables app timeout to prevent termination during debugging sessions. When `false`, enables normal timeout behavior which may kill paused apps. See troubleshooting section for details.
enableDebug	Attach debugger on launch (default: true)

Sample configurations

Basic React Native for Vega app

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(script) Launch",
            "type": "kepler",
            "request": "launch",
            "keplerMode": "debug",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}",
            "disableAppTimeout": true,
            "perf": {
                "startActivityMonitoring": false
            }
        }
    ]
}

Multi-device React Native for Vega app

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(script) Launch on selected device",
            "type": "kepler",
            "request": "launch",
            "keplerMode": "debug",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}",
            "disableAppTimeout": true
        },
        {
            "name": "(script) Launch on Vega Virtual Device",
            "type": "kepler",
            "request": "launch",
            "keplerMode": "debug",
            "cwd": "${workspaceFolder}",
            "deviceId": "KeplerVirtualDevice",
            "disableAppTimeout": true
        }
    ]
}

Hybrid React Native and Turbo Module debugging

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(script) Attach",
            "type": "kepler",
            "request": "attach",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}"
        },
        {
            "name": "(native) Attach",
            "type": "keplerNative",
            "request": "attach",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}",
            "debugger": "gdb"
        }
    ],
    "compounds": [
        {
            "name": "Hybrid Debugger",
            "configurations": ["(native) Attach", "(script) Attach"]
        }
    ]
}

Configuration snippets

Name	Description	When to use
(script) Launch	Debug React Native for Vega apps on selected device	Starting new debugging session for JavaScript/TypeScript code
(script) Launch - Perf	Launch in release mode with performance monitoring	Performance analysis (not available on Vega Virtual Device)
(script) Attach	Attach to running Vega app for React Native debugging	App already running, want to debug JavaScript/TypeScript code
(native) Launch	Debug Turbo Module native code on selected device	Starting new session to debug native C++ code
(native) Attach	Attach to running app for native code debugging	App already running, want to debug native C++ code

Debug your app

Once you’ve configured your debugger and set up breakpoints, start debugging your app on your chosen target device. The debugging process is similar for both devices, with device selection being the main difference.

Debug on Vega Virtual Device

Select Virtual Device from the sidebar.
Go to Run and Debug.
Select the (script) Launch config from the dropdown.
Click the play icon or press F5.

Vega Studio packages, loads, and executes your app on the Vega Virtual Device. When execution hits a breakpoint, VS Code enters debug mode and displays the Debug Toolbar. Screenshot showing the VS Code debug mode with Debug Toolbar and an active console.

Screenshot showing the VS Code debug mode with Debug Toolbar and an active console.

Debug on Fire TV Stick

Select Fire TV Stick as your target.
Go to Run and Debug.
Select the (script) Launch config from the dropdown.
Click the play icon or press F5.

Vega Studio packages, loads, and executes your app on the Fire TV Stick. When execution hits a breakpoint, VS Code enters debug mode and displays the Debug toolbar. The debug toolbar contains actions you can perform during a debugging session. Screenshot showing the debug toolbar controls for stepping through code execution in VS Code.

Screenshot showing the debug toolbar controls for stepping through code execution in VS Code.

Action	Description
Continue/Pause	Resume execution to next breakpoint or pause current execution
Step Over	Execute next method without entering its details
Step Into	Enter next method to debug line-by-line
Step Out	Complete current method and return to caller
Restart	Restart debugging session with current configuration
Stop	Terminate debugging session

Troubleshooting

For debugging issues, see Fix Debugging Issues.

​Prerequisites

​Configure the Vega Studio debugger

​Automatic configuration

​Manual configuration

​Specify your target device

​Add configuration to launch.json

​Set up breakpoints

​Launch.json attributes

​Sample configurations

​Configuration snippets

​Debug your app

​Debug on Vega Virtual Device

​Debug on Fire TV Stick

​Debug toolbar actions

​Troubleshooting

​Related topics