Debug B2C Commerce server-side scripts using the b2c CLI. Use this skill whenever the user needs to set breakpoints, step through code, inspect variables, evaluate expressions, or investigate runtime behavior on a B2C Commerce instance. Also use when the user wants to understand what a script is doing at runtime, capture state at a specific line, or drive the debugger from a headless script — even if they just say "debug this controller" or "what's the value of basket at line 42".
Debug B2C Commerce server-side scripts using the b2c CLI. Use this skill whenever the user needs to set breakpoints, step through code, inspect variables, evaluate expressions, or investigate runtime behavior on a B2C Commerce instance. Also use when the user wants to understand what a script is doing at runtime, capture state at a specific line, or drive the debugger from a headless script — even if they just say "debug this controller" or "what's the value of basket at line 42".
B2C Debug Skill
Debug server-side scripts on Salesforce B2C Commerce instances — set breakpoints, step through code, and inspect variables in SFRA controllers, hooks, jobs, and custom APIs.
Prefer the MCP diagnostics tools when available. If the B2C DX MCP server is installed (tools named debug_start_session, debug_set_breakpoints, debug_wait_for_stop, debug_capture_at_breakpoint, etc.), use them instead of the RPC-based b2c debug cli --rpc workflow. The MCP tools manage session state for you, return structured JSON, and support a non-blocking poll workflow (debug_list_sessions / debug_wait_for_stop) that is far more reliable for agents than driving JSONL over stdio. Only fall back to b2c debug cli (REPL or --rpc) when the MCP server is not installed, or when a human wants an interactive terminal session.
b2c debug provides a Debug Adapter Protocol (DAP) debug adapter for IDEs. For terminal or headless use without the MCP tools, b2c debug cli also offers an interactive REPL and a JSONL --rpc mode.
Tip: If b2c is not installed globally, use npx @salesforce/b2c-cli instead (e.g., ).
npx @salesforce/b2c-cli debug cli
Configuration & Authentication
The CLI auto-discovers the target instance and credentials from SFCC_* environment variables, dw.json in the current or parent directories, ~/.mobify, package.json, and configuration plugins. Flags like --server, --username, and --password are usually unnecessary — only pass them to override what's auto-detected.
Run b2c setup inspect to see the resolved configuration and which source provided each value (use --json for scripting, --unmask to reveal secrets). For precedence rules and troubleshooting, see the b2c-cli:b2c-config skill.
Prerequisites
Basic Auth credentials for a BM user with WebDAV_Manage_Customization: a username and either the account password or a WebDAV File Access and UX Studio access key
Interactive Debugging
Start a Debug Session
# Start interactive debugger
b2c debug cli
# Specify cartridge directory for source mapping
b2c debug cli --cartridge-path ./cartridges
# Use a custom client ID (for concurrent sessions)
b2c debug cli --client-id my-session
stack
vars
members basket.productLineItems
eval basket.productLineItems.length
eval request.httpParameterMap.get("pid").stringValue
Control Execution
continue
step
stepin
stepout
Thread Management
threads
thread 5
frame 2
RPC Mode (Headless / Agent Use)
For headless scripts, agents, and programmatic integration, use --rpc mode. Commands and responses are JSONL (one JSON object per line) on stdin/stdout.
This starts a DAP debug adapter over stdio, used by IDE launch configurations.
Server Affinity (Hitting Breakpoints)
A breakpoint only fires when the triggering code runs on the same application server the debugger is attached to. Some Production Instance Group (PIG) environments run multiple application servers behind a load balancer, so a request that should hit your breakpoint may land on a different app server 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. If breakpoints are not hitting on a sandbox, the cause is something else (wrong path mapping, code version, or the code simply not running).
To pin a triggering request to the correct app server, send it with the debugger's session cookie (dwsid):
MCP:debug_start_session and debug_list_sessions return a session_cookie ({name, value}). Send the request that triggers your code (storefront page load, SCAPI/OCAPI call) with Cookie: dwsid=<value>.
Any trigger: whatever issues the request — a browser, curl, an integration test — must carry the same dwsid value.
Headless requests (hooks, custom APIs, server-to-server SCAPI/OCAPI): instead of a cookie, pass the value as the sfdc_dwsid request header (sfdc_dwsid: <value>).
If the cookie or header cannot be set on the triggering request, retry until the load balancer routes to the attached app server.
Related Skills
b2c-cli:b2c-logs - Retrieve server logs for investigating errors found during debugging
b2c-cli:b2c-code - Deploy code changes before debugging
b2c-cli:b2c-config - Verify instance configuration and credentials
