Back to VS Code home

Debug configurations

The Ballerina debugger supports various debug configuration options added via a JSON configuration file.

Create the configuration file

Follow the steps below to generate the launch.json configurations file with the default attributes.

Info: Creating the launch.json file enables the Ballerina Program, Ballerina Test, and Ballerina Remote options that are required to debug your code using configurations.

  1. Open the folder, which includes the Ballerina program you want to debug and select the file.

  2. Press the Ctrl + Shift + D keys (for macOS: ⌘ + ↑ + D) to launch the Debugger view.

  3. Click create a launch.json file and then select Ballerina Debug as the Environment.

    Info: This generates a launch.json file in your workspace root under the .vscode directory. You can edit the configuration attributes to perform advanced debugging operations.

  4. Add/edit the relevant configurations for debugging in the opened launch.json file.

Default configurations

Given below are the default configurations generated in the launch.json file for debugging Ballerina.

Copy
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Ballerina Debug",
            "type": "ballerina",
            "request": "launch",
            "programArgs": [],
            "commandOptions": [],
            "env": {}
        },
        {
            "name": "Ballerina Test",
            "type": "ballerina",
            "request": "launch",
            "debugTests": true,
            "programArgs": [],
            "commandOptions": [],
            "env": {}
        },
        {
            "name": "Ballerina Remote",
            "type": "ballerina",
            "request": "attach",
            "debuggeeHost": "127.0.0.1",
            "debuggeePort": "5005"
        }
    ]
}

Configuration attributes

You can edit the configurations of the auto-generated launch.json file, which is located in your workspace root under the .vscode directory.

Info: This file consists of three debug configurations named Ballerina Debug, Ballerina Test, and Ballerina Remote. Each configuration supports a different set of attributes, which will be provided via IntelliSense completion suggestions.

Attributes for all configurations

The following attributes are mandatory for all configurations.

AttributeDescription
nameThe reader-friendly name to appear in the debug launch configuration drop-down menu.
typeThe type of debugger to use for this launch configuration. The attribute value must be kept as ballerina for all Ballerina debug configuration types.
requestThe request type of this launch configuration. Currently, launch and attach are supported.

Attributes for the launch configurations

The following attributes are supported by all the Ballerina launch configurations related to the Ballerina code available locally.

AttributeDescription
programArgsAny program arguments that are required to be passed into the main function of the Ballerina program to be launched can be passed as a list of strings.
commandOptionsIf required, you can configure command options for the Ballerina program to be launched as a list of strings. You can see the list of all the available command options by executing the following CLI commands in your terminal.

- For the Ballerina debug configuration: bal run --help
- For the Ballerina test configuration: bal test --help
envAny environment variables you need to configure for launching the Ballerina program can be passed as a map of strings (name and value).
debugTestsIndicates whether to debug the tests for the given script.
terminalBy setting this attribute value to integrated, you can launch the Ballerina program in a separate integrated VS Code terminal. The program evaluations can be carried out on the Debug Console as usual.

Attributes for the attach configurations

The following attributes are supported by all the Ballerina attach configurations related to the Ballerina code available remotely.

AttributeDescription
debuggeeHostHost address of the remote process to be attached (if not specified, the default value will be the localhost(127.0.0.1)).
debuggeePortPort number of the remote process to be attached.