B2c Debug

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.

For MCP debugging, pass projectDirectory to debug_start_session whenever the MCP server may have been launched outside the project. The tool uses that root to load the project's .env and default dw.json; pass configPath to select a different primary dw.json-format file and instanceName to select a named instance from the primary or shared default file. Cartridge discovery and local/server source mapping default to projectDirectory; pass cartridgeDirectory only when the cartridges live under a different root. The start call captures this information in resolution, which debug_list_sessions returns without requiring the caller to repeat it. The MCP server controls its SDAPI client identity internally, so callers do not pass a debugger client ID.

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

Set Breakpoints

In the REPL:

break Cart.js:42
break Checkout.js:100 if basket.totalGrossPrice > 100
breakpoints
delete 1

Inspect State When Halted

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.

b2c debug cli --rpc

Send Commands

{"id": 1, "command": "set_breakpoints", "args": {"breakpoints": [{"file": "Cart.js", "line": 42}]}}
{"id": 2, "command": "get_stack"}
{"id": 3, "command": "get_variables", "args": {"scope": "local"}}
{"id": 4, "command": "evaluate", "args": {"expression": "basket.totalGrossPrice"}}
{"id": 5, "command": "continue"}

Receive Responses and Events

{"event": "ready", "data": {}}
{"id": 1, "result": {"breakpoints": [{"id": 1, "file": "Cart.js", "line": 42, "script_path": "/app_storefront/cartridge/controllers/Cart.js"}]}}
{"event": "thread_stopped", "data": {"thread_id": 5, "location": {"file": "Cart.js", "line": 42, "function_name": "show"}}}

Available RPC Commands

DAP Mode (IDE Integration)

For VS Code and other DAP-compatible IDEs:

b2c debug

This starts a DAP debug adapter over stdio, used by IDE launch configurations.

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