Script Debugger

The B2C Commerce Script Debugger lets you set breakpoints, step through code, and inspect variables in server-side scripts — SFRA controllers, hooks, jobs, custom SCAPI endpoints, or any dw/* cartridge code — running live on an instance. The tooling connects to the instance's Script Debugger API (SDAPI) and surfaces it several ways:

• VS Code (recommended) — the B2C DX VS Code Extension provides the full graphical debugger: breakpoints, log points, watch expressions, and step controls, just like any other Node project. This is the primary interface for interactive debugging.
• Other IDEs (JetBrains, etc.) via the Debug Adapter Protocol (DAP) adapter — b2c debug.
• AI-agent debugging via the MCP diagnostics tools — debug_start_session, debug_set_breakpoints, etc.

The CLI's DAP debug adapter (b2c debug) also offers a headless terminal mode for scripting; see Debug Commands for details.

Requirements

The debugger needs two things:

1. The Script Debugger enabled on the instance. In Business Manager: Administration → Development Configuration → Script Debugger → Enable.
2. Basic auth credentials — a Business Manager username and a WebDAV / UX Studio access key (used as the password). OAuth/client credentials are not sufficient for the SDAPI.

The access key is the same kind of WebDAV access key used by UX Studio and other code-upload tooling. Generate one in Business Manager under your account's access keys. See the Authentication Guide for details.

Only one debug client per client_id may be attached to a host at a time. Starting a new session with the same client_id takes over (replaces) any prior one — a useful safety net for orphaned sessions.

Configuration

The debugger reads the same resolved configuration as the rest of the CLI. Provide the hostname and Basic auth credentials via any of (highest priority first):

• Flags — --username / --password (and the active instance for the hostname)
• Environment variables — SFCC_SERVER, SFCC_USERNAME, SFCC_PASSWORD
• dw.json — hostname, username, password fields

See CLI Configuration for the full resolution order and multi-instance setup.

Choosing an interface

Use case	Interface	Reference
Debug from VS Code (recommended)	B2C DX VS Code Extension	VS Code Extension
Debug from another IDE (JetBrains)	b2c debug (DAP debug adapter over stdio)	Debug Commands
Let an AI agent drive the debugger	MCP diagnostics tools	Diagnostics Tools

They all share the same underlying workflow: connect a session, set breakpoints (by local file path, cartridge-prefixed path, or server path), trigger the code on the instance, then inspect the halted thread.

Server affinity (hitting breakpoints)

A breakpoint only fires when the code runs on the same application server the debugger is attached to. On a single-app-server environment this is automatic. But some Production Instance Group (PIG) environments run multiple application servers behind a load balancer — there, a request that triggers your code may land on a different app server than the debugger, and the breakpoint never fires.

Sandboxes (ODS) are single-app-server and are not affected. This only matters on certain multi-app-server PIG environments.

To pin a triggering request to the correct app server, route it with the debugger's session cookie (dwsid). The CLI and SDK manage this cookie automatically for the debugger's own requests — so the way you obtain the value depends on the interface:

• MCP: debug_start_session and debug_list_sessions return a session_cookie ({name, value}). This is the most direct source. See Diagnostics Tools → Server affinity.
• VS Code: the cookie is logged to the B2C DX output channel when the session connects, and the Copy Debugger Session ID (dwsid) command copies it to your clipboard.
• CLI: the cookie is logged at info level when the session connects (Debug session cookie: dwsid=…).

Once you have the value, send the request that triggers your code — a browser session, curl, an integration test — with that cookie:

Cookie: dwsid=<value>

For headless requests where you can't (or don't want to) set a cookie — server-to-server calls that trigger hooks, custom APIs, or SCAPI/OCAPI endpoints — pass the same value as the sfdc_dwsid request header instead:

sfdc_dwsid: <value>

If you cannot set the cookie or header on the triggering request, you may need to retry until the load balancer happens to route to the attached app server.

A future enhancement will let the VS Code extension launch a browser pre-seeded with the debug session's cookie, removing this manual step.

See Also

• VS Code Extension — the recommended graphical debugger
• Debug Commands — b2c debug DAP debug adapter reference
• Diagnostics Tools — MCP tools for agent-driven debugging
• Authentication Setup — WebDAV access key configuration
• IDE Integration — connecting other IDEs to your CLI configuration