Debugging

The VS Code Ballerina extension allows you to either run your Ballerina program (without debugging) or debug them easily by launching its debugger.

Info: For more information on debugging your code using VS Code, go to the VS Code Documentation.

Starting a Debug Session

The VS Code Ballerina extension gives you the same debugging experience as the conventional VS Code Debugger. Follow the steps below to start a debug session.

Start Debug Session


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

  2. Press the Control + Shift + D keys (for Mac: Command + Shift +D) to launch the Debugger view.

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

    You view the opened launch.json file.

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

  5. Add the debug points you require by clicking in front of the line numbers of the file you want to debug.

Then, you can start a program, test, or remote debug session as shown below.

Info: If you launch the debug session through VS Code, the working directory will be the Ballerina package root. However, you can use remote debugging for alternative working directories.


Starting a Program Debug Session

Follow the steps below to start a program debug session.

  1. Select Ballerina Debug from the drop-down available in the upper left corner to start a program debugging session.

  2. Click the Start Debugging icon on the upper left corner to start debugging.

    You view the output in the DEBUG CONSOLE.

    Program Debug


Starting a Test Debug Session

Follow the steps below to start a test debug session.

  1. Select Ballerina Test from the drop-down available in the upper left corner to start a test debugging session.

  2. Click the Start Debugging icon on the upper left corner to start debugging.

    You view the output in the DEBUG CONSOLE.

    Test Debug


Starting a Remote Debug Session

Follow the steps below to start a remote debug session.

  1. Select Ballerina Remote from the drop-down available in the upper left corner to start a remote debugging session.

  2. Open the Terminal and execute the Ballerina command, which you want to debug, out of the supported remote debugging commands below.

    • Debugging a Ballerina package or a single file:
     bal run --debug <DEBUGGEE_PORT> <BAL_FILE_PATH/PACKAGE_PATH>
    
    • Debugging Ballerina executable JAR:
     bal run --debug <DEBUGGEE_PORT> <EXECUTABLE_JAR_FILE_PATH>
    
    • Debugging Ballerina tests:
     bal test --debug <DEBUGGEE_PORT> <PACKAGE_PATH>
    
    • Debugging Ballerina tests during the build:
     bal build --debug <DEBUGGEE_PORT> <PACKAGE_PATH>
    

    The terminal will show the following log:

     Listening for transport dt_socket at address: 5005
    
  3. Click the Start Debugging icon on the upper left corner to start debugging.

    You view the output in the DEBUG CONSOLE.

    Remote Debug


Running Without Debugging

Follow the steps below to run your program (without debugging).

  1. On the VSCode editor, open the Ballerina program file you want to run.

  2. Click Run in the top menu, and then click Run Without Debugging.

  3. Select Ballerina Debug as the Environment.

You view the program being executed in the DEBUG CONSOLE as shown below.

Run Without Debugging


Using the Debugging Features

Visual Studio Code allows you to debug Ballerina programs through the Ballerina extension. The debugging features below are supported by Ballerina.

  • Launch/Attach
  • Breakpoints
  • Pause & Continue
  • Step In/Out/Over
  • Variables
  • Call Stacks
  • Strands
  • Expression Evaluation

Info The Ballerina debugger is an open-source project and contributors are most welcome to get engaged with it via the ballerina-lang GitHub repository. If you encounter any difficulties when using this feature, feel free to create an issue on it.

Using Expression Evaluation

Ballerina expression evaluator allows evaluating Ballerina variables and expressions at runtime allowing them to be viewed when the IDE is in the break mode.

The Ballerina VSCode debugger lets you evaluate expressions in the ways below.

Using the Debug Console

Debugger Evaluation Console


Using the Watch Window

Debugger Watch Window


Existing Limitations

The features below are currently not supported.

  • Anonymous function, query, let, and constructor expressions
  • Qualified identifiers (Hence, cannot evaluate imported module entities.)
  • Function invocations with rest arguments
  • Action invocations

Debug Configurations

Ballerina debugger supports various debug configuration options via launch.json file. You can either add configurations to the existing launch.json file (which is located in your workspace root under the .vscode directory), or you can generate launch.json configurations file with default values by,

  1. Click the Run and Debug icon in the left menu or press the Control + Shift + D keys, to launch the Debugger view. (for Mac - Command + Shift +D).

  2. Click on create a launch.json file and then select Ballerina Debug.

Run And Debug


Ballerina Debug


Here are the default configurations generated for the Ballerina debugging:

Debug Configurations


Info: You can debug a Ballerina program without generating the launch.json configurations file, but it is not possible to manage launch configurations and set up advanced debugging.

Ballerina launch.json attributes

The auto-generated launch.json file consists of three main configurations, namely, Ballerina Debug, Ballerina Test, and Ballerina Remote. Each configuration supports different attributes, and those attributes can be identified with the help of IntelliSense suggestions (⌃Space).

The following attributes are mandatory for all configurations.

  • name - The reader-friendly name to appear in the Debug launch configuration dropdown.
  • type - The type of debugger to use for this launch configuration. The attribute value must be kept as ballerina for all Ballerina debugging configuration types.
  • request - The request type of this launch configuration. Currently, launch and attach are supported.

The following attributes are supported for all Ballerina launch configurations.

  • programArgs - Any 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.
  • commandOptions - If 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 Ballerina Debug configuration:
      bal run --help
    
    • For Ballerina Test configuration:
      bal test --help
    
  • env - Any environment variables you need to configure for the launching Ballerina program can be passed as a map of strings (name and value).
  • debugTests - Indicates whether to debug the tests for the given script.

The following attributes are supported for all Ballerina attach configurations.

  • debuggeeHost - Host address of the remote process to be attached (If not specified, the default value will be the localhost(127.0.0.1)).
  • debuggeePort - Port number of the remote process to be attached.