Debugging Apps in VS Code

This guide explains how to debug the Pascal units of a Niksphere application directly from Visual Studio Code, using the Niksphere VS Code Extension's built-in debugger. You can set breakpoints, step through code, and inspect local variables while a real Niksphere Engine executes your app.

Prerequisites

1. Visual Studio Code (v1.80.0 or later).
2. Niksphere VS Code Extension installed.
3. Niksphere CLI (nik) installed (see Niksphere CLI Installation & Setup Guide).
4. Niksphere Engine local/remote instance (see Niksphere Engine Installation & Setup Guide) or a cloud environment.

1. How It Works

The VS Code extension declares a niksphere debugger type backed by nik dev dap: a Debug Adapter Protocol (DAP) server that VS Code spawns as a subprocess and that proxies your debugging session to the target Engine's /api/v1/admin/dap control connection. Every debugging session is configured through your project's .vscode/launch.json file — there is no zero-configuration default beyond the one shortcut described in Section 5.

IMPORTANT

environmentUrl is required in every niksphere launch.json configuration. Unlike publishing or app management, debugging never falls back to the sidebar's active environment — if it's missing, VS Code shows an error and refuses to start the debug session.

Only one debug client can be attached to a given Engine at a time. If you try to start a second debugging session while one is already attached, the new one is rejected.

There are three ways to start a debugging session, each a distinct request value in .vscode/launch.json.

2. Starting & Debugging a New Session (launch)

Use this to iterate on code changes: it compiles and publishes your current workspace, arms the debugger for the next session, and then opens the environment's frontend in your browser to provoke a new connection automatically.

{
  "type": "niksphere",
  "request": "launch",
  "name": "Start & Debug New Niksphere Client Session",
  "environmentUrl": "http://localhost:3000"
}

Press F5. The extension:

1. Compiles and publishes the app at appPath (defaults to the workspace folder, as above) to environmentUrl (equivalent to nik dev publish <appPath> -s <environmentUrl>), showing progress in a notification.
2. Arms the Engine for the next session and starts the DAP session.
3. Opens environmentUrl in your default browser once the Engine confirms it's armed — this reliably provokes a fresh client connection without a race between "browser opens" and "Engine is ready."

Because launch always republishes first, it debugs your current code — not whatever was last published. Use plain attach instead if you don't want a republish (for example, when attaching to a shared staging environment you don't want to redeploy).

3. Attaching to an Already-Running Session

Use this to debug a specific client session that is already connected to the Engine — for example, one a tester or a colleague is currently using.

1. Find the session's ID in the Sessions view in the Niksphere sidebar (Activity Bar → Niksphere → Sessions).
2. Add a configuration to .vscode/launch.json:

   {
     "version": "0.2.0",
     "configurations": [
       {
         "type": "niksphere",
         "request": "attach",
         "name": "Debug Niksphere Session abc123",
         "environmentUrl": "http://localhost:3000",
         "sessionId": "abc123"
       }
     ]
   }

3. Press F5 (or Run and Debug → select the configuration). The debugger attaches directly to that session's already-running VM — nothing is recompiled, republished, or restarted, since the whole point is to inspect a session exactly as it currently is.
4. Set breakpoints in your .pas unit files as usual. The next time that session executes code through a breakpointed line, execution pauses in VS Code.

4. Attaching to the Next New Client Session

Use this to debug whichever client connects next — useful when you're about to trigger a new session yourself (e.g. by opening the app's frontend) or don't know a session ID in advance.

{
  "type": "niksphere",
  "request": "attach",
  "name": "Debug Next Niksphere Client Session",
  "environmentUrl": "http://localhost:3000"
}

Press F5. The Debug Console shows:

Connected to http://localhost:3000 and waiting for the next client session to attach...

Once any new client connects, the Debug Console confirms it (Client session <sessionId> attached.) and the debugger takes over that session's VM for the rest of its lifetime — not just its first request.

5. Quick Start Without a launch.json Entry

If your workspace already has a niksphere attach configuration (without a sessionId) somewhere in .vscode/launch.json, you can also start that same flow from the Command Palette without selecting it manually: run Niksphere: Debug Next Client Session. It reuses that configuration's environmentUrl/appPath — if none exists yet, it tells you to add one first.

6. Debugging Once Attached

• Breakpoints are set directly in your .pas files, the same way as any other VS Code debugger. A breakpoint only turns into a filled (verified) dot if it falls on an executable statement boundary in the currently published bytecode.
• Supported step actions: Continue, Step Over, and Step Into. Step Out is not currently supported.
• Variables: the currently paused stack frame's locals are shown in the Variables panel.
• A debugging session stays attached across many requests to the same client session — it only ends when that session actually disconnects, is reloaded (e.g. because the Engine recompiled in the background), or is terminated by an administrator.

7. Troubleshooting

'environmentUrl' is required in this launch.json configuration

Add an explicit environmentUrl to the configuration you're starting — there is no fallback to the sidebar's active environment for any of the three debug flows.

Add a 'niksphere' attach configuration with 'environmentUrl' to launch.json before using this command

Shown by Niksphere: Debug Next Client Session when no matching configuration exists yet. Add one as shown in Section 4, or use the Run and Debug view directly instead of the command.

session <sessionId> not found

The session you tried to attach to has already disconnected, or the ID was mistyped. Re-check the Sessions view for a currently connected session.

A debug client is already attached

Only one debugging session can be attached to an Engine at a time. Stop the existing session (or wait for it to disconnect) before starting a new one.

Related Documentation

• Developing & Publishing Apps in VS Code: Compiling and publishing without debugging.
• Managing Environments & Apps in VS Code: Finding an environment's URL and managing app installs.
• VS Code Extension Reference: Full settings, commands, and tasks reference.