Skip to Content
Technical Articles
Author's profile photo Arley Triana Morin

Set Up Remote Debugging to Diagnose CAP Applications (Node.js Stack) at Runtime Running on SAP BTP, Cloud Foundry Environment



In this blog post, you learn how to set up remote debugging for a deployed CAP application instance running on SAP BTP, Cloud Foundry environment.

As a developer, this is one of the go methods when your application is misbehaving, and you can’t troubleshoot just by analyzing the logs or/and you can’t reproduce runtime errors on your development environment (local machine).

With remote debugging, you can use your local development environment to inspect and interact with the application to diagnose problems efficiently.
Disclaimer: It isn’t advisable to enable remote debugging for an application running on production.

The major topics that are covered include:

  • Authenticate to Cloud Foundry with the CLI
  • Connect to a Cloud Foundry application instance using the Secure Shell protocol (SSH)
  • Enable the Node.js inspector for remote debugging on a running application instance
  • Enable port forwarding to Cloud Foundry
  • Attach a Node.js debugger to a process running on a Cloud Foundry application instance


Step 1: Install and Verify the Cloud Foundry Command Line Interface (CLI) Installation


To install the Cloud Foundry CLI, following the official guide.

To verify the installation, open a new command prompt session and run:

╰─$ cf -v

If your installation was successful, the Cloud Foundry CLI version is displayed to standard output.

cf version 7.2.0+be4a5ce2b.2020-12-10


Step 2: Log In to the Cloud Foundry Instance with the CLI and SAP Single Sign-On


To log in to the Cloud Foundry, the cf login command is used.

cf login [-a API_URL] [-o ORG] [-s SPACE] [--sso]


  • API-URL is your API endpoint (for example,
  • ORG is the org name where your application is deployed. Orgs map to business units have quota plans and unique roles.
  • SPACE is the space in the organization where your application is deployed. Spaces map to teams or products, hold applications, and have unique roles.
  • --sso Prompt for a one-time passcode to log in. SAP Single Sign-On is the safest and most recommended way to log in.

The org name, API endpoint and space information can be found in the SAP BTP Cockpit under HomeRegionsGlobal AccountsSubaccounts.

SAP BTP Cockpit Overview Screen

SAP BTP Cockpit Overview


Sample usage of the cf login command:

╰─$ cf login -a -o myorg -s myspace --sso
API endpoint:

Temporary Authentication Code ( Get one at ):

After running cf login with the --sso option, the Cloud Foundry CLI prompts for a one-time passcode to log in. Open a browser window, go to the URL , authenticate →

SAP BTP SAP Single Sign-On


SAP BTP Temporary Authentication Code

SAP BTP Temporary Authentication Code


, copy the one-time passcode, go back to the console and paste it into the prompt. Once authenticated, details of the targeted org and space are provided.

Temporary Authentication Code ( Get one at ):

Targeted org myorg.

Targeted space myspace.

API endpoint:
API version:    3.99.0
org:            myorg
space:          myspace

Note that Cloud Foundry uses a role-based access control system to grant permissions to members, so make sure you’ve got the appropriate role permissions assigned. For example, by being an org auditor.

Step 3: Connect to a Cloud Foundry Application Instance Using SSH


Cloud Foundry allows you to SSH to application instances unless an org/space manager has prohibited this access. For more detailed information, you can refer to Enable and Disable SSH Access.

The cf ssh-enabled command checks whether an application is accessible via SSH:

╰─$ cf ssh-enabled myapp
ssh support is enabled for app 'myapp'.

If the app isn’t accessible via SSH, it can be enabled with the command cf enable-ssh.

╰─$ cf enable-ssh myapp
Enabling ssh support for app myapp as

Note that if a space manager disabled the access at the space level, all the applications that are part of this space would inherit the access level, and you as a developer won’t be able to SSH to an individual application container even if you enabled SSH access at the application level.

If SSH access is allowed at the deployment, space, and application level, you can run the cf ssh myapp command to start an interactive SSH session with the VM container hosting the application.

╰─$ cf ssh myapp


Step 4: Enable the Node.js Inspector for Remote Debugging on a Running Application Instance


To enable debug mode for a running Node.js process, you need to know its unique process ID (PID). On Linux and Unix-like environments, the ps command gives you the information required.

vcap@afa9bea3-b619-6476-5e97-1328:~$ ps aux

vcap    151  0.0  0.1 687580 118376 ?       Sl   May28   0:05 node /home/vcap/deps/0/bin/npx cds run

Once the PID of the Node.js process running the application is known, you can use the kill command to send a debugging signal to it. The Node.js runtime activates the inspector protocol when it receives a usr1 signal. The inspector protocol is more or less a debugging protocol that allows tools to instrument, inspect, debug, and profile.

vcap@afa9bea3-b619-6476-5e97-1328:~$ kill -usr1 151

After sending this signal to the Node.js process, inspect the application logs, you see that a debugger is listening on ws://, this means that the Node.js process is switched into debug mode and start listening for debugging request on a WebSocket server at host and port BTP Cockpit Application Logs

SAP BTP Cockpit Application Logs


Step 5: Enable Port Forwarding to Cloud Foundry


With port forwarding or port mapping, you can redirect TCP requests from your development machine to an application instance running on a VM.
In Cloud Foundry, port forwarding works by creating a listening TCP port on your local machine that maps to a TCP port on the VM via a secure SSH channel.

When using the cf ssh command,

the -L flag enables local port forwarding, binding an output port on your machine to an input port on the application VM. Pass in a local port and your application VM port and port number, all colon-delimited. You can prepend your local network interface or use the default localhost.

Enables local port forwarding


Port forwarding sample usage:

cf ssh -N -L 9229: myapp

This starts an SSH tunnel session where a connection to port 9229 on your development environment is forwarded to myapp instance on port 9229.

You can now attach a debugger such as Visual Studio Code or Chrome DevTools to localhost:9229. With this setup, you should be able to debug your application instance running on SAP BTP, Cloud Foundry environment, as if the Node.js application was running locally.


Step 6: Attach a Node.js Debugger to a Process Running on a Cloud Foundry Application Instance


Node.js debuggers typically support attaching to an already running program in debug mode. In VS Code and Chrome DevTools, there’s a built-in “Attach to Node Process” debugging model.


Attach VS Code Debugger


Add the following debug configuration to your launch.json file.

    "name": "Attach to a Cloud Foundry Instance on Port 9229",
    "port": 9229,
    "request": "attach",
    "type": "node",
    "localRoot": "${workspacefolder}",
    "remoteRoot": "/home/vcap/app"

For example:

VS Code Debug Configuration

VS Code Debug Configuration

For detailed information on how to add a new debug configuration, refer to Add a new configuration.

Then on the sidebar, click on Run and Debug.

Then click on Start Debugging.

Open the Debug Console.

VS Code Debugger Console, Loaded Scripts ..

VS Code Debugger Console, Loaded Scripts …

At this point, if you followed the previous steps, you should be able to interact with the REPL, source code, and set breakpoints.


Attach Chrome DevTools


Open the Chrome browser or any Chromium-based browser and enter chrome://inspect in the address bar. Microsoft Edge also uses the same V8 JavaScript engine, and can thus use the same debugger.


Chrome Browser Window

Chrome Browser Window


After navigating to the URL, you’ll see following page:

Chrome Browser Window (Inspect Devices Screen)


Chrome Browser Window (Inspect Devices)

Under the Devices, click the Open dedicated DevTools for Node link, and a new window pop up for debugging a node session:

Chrome DevTools Node.js Debugger


Chrome DevTools Node.js Debugger


Chrome Debugger Console Panel

Chrome Debugger Console Panel

At this point, if you followed the previous steps, we’re now able to debug, interact with the REPL, source code, and set breakpoints.

Chrome Debugger Sources Panel

Chrome Debugger Sources Panel


CLOUD FOUNDRY, the CLOUD FOUNDRY logo, and other CLOUD FOUNDRY marks used in this block post are trademarks of the Foundation in the United States and other countries.

Assigned tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo David Kunz
      David Kunz

      Hey Arley Triana Morin,

      Thanks a lot for sharing, this is borderline magic!

      It even works with Neovim (using nvim-dap), so no more console.log on remote systems for me.

      Best regards,

      Author's profile photo Shadab Alam
      Shadab Alam

      I miss the days of the good old /H    🙁