Skip to Content
Debugging

Script Debugger

Debug SFCC server-side JavaScript and Digital Script from a JetBrains IDE with line breakpoints, stepping, scopes and Evaluate Expression

Intellij SFCC connects the IDE's debugger to the SFCC Script Debugger API of your instance. Set a breakpoint in a controller, script or hook, load the page and the IDE stops on that line with the call stack and live variables

The console links each breakpoint path to its file. When a request reaches the breakpoint, Frames lists the cartridge, file and line of every call and Variables shows the Local, Closure and Global scopes, with completion from the live objects in the Evaluate field

Before you start

NeedsWhy
An active connection with a valid accountThe debugger signs in with the connection selected in the main toolbar, see Connections
At least one linked cartridgeBreakpoints outside linked cartridges and modules aren't sent, see Cartridges & Modules
The same code on the instanceBreakpoints match by file path and line. Upload the code or turn on Auto Upload
A valid license or trialSee Purchase & License

Start a session

Add the configuration

Open Run › Edit Configurations, click + and choose Salesforce B2C Commerce (SFCC). There is nothing to fill in. Name it, for example "SFCC Debug", and save

Start it with Debug

Select the configuration in the run widget and click Debug. Run is unavailable on purpose, even though its settings page says to run it

Wait for the connection

The Debug tool window opens. A balloon and the console report "Connected to" with the host, see The session console

Trigger the code

Set a breakpoint in the gutter of a .js or .ds file in a linked cartridge, then open the page or call the endpoint that runs it

app_custom/cartridge/controllers/Account.js
server.append('Show', function (req, res, next) {
    var viewData = res.getViewData(); // set a breakpoint here
    viewData.loyaltyTier = req.currentCustomer.raw.profile.custom.loyaltyTier;
    res.setViewData(viewData);
    next();
});

Open https://<host>/on/demandware.store/Sites-RefArch-Site/default/Account-Show to stop there

The session console

The Console tab logs what the debugger does. Every line starts with the date and time, such as [2026-10-11 10:42:07]

LineWhen it appears
"Connected to" and the hostThe session signed in to the Script Debugger API
"Waiting for breakpoint" and a cartridge path with the line, such as app_custom/cartridge/controllers/Cart.js:7The instance accepted a breakpoint, at session start and each time you add one
"Removed breakpoint" and the pathYou removed or moved a breakpoint
"Disconnected from" and the hostYou stopped the session

Cartridge paths are links that open the file at that line. Instance errors print in red, see Troubleshooting

Breakpoint options

The instance knows a breakpoint's path, line and condition. The plugin applies the other options itself when a request stops

OptionWhat happens
Suspend turned offThe plugin logs what the breakpoint asks for and resumes the request
"Breakpoint hit" messagePrinted in the console on every stop
Stack tracePrinted in the console on every stop
Remove once hitRemoved after its first stop
Disable until hitting the following breakpointWorks as usual
ConditionChecked by the instance, so the breakpoint stops only when it is true
Evaluate and logEvaluated in the stopped frame and printed in the console. With Suspend turned off, the request runs on

While paused

ControlWhat it does
Step Over, Step Into, Step OutStep through the paused request
ResumeContinue until the next breakpoint
FramesThe call stack, under "Thread" and its ID. Each frame reads "cartridge: file:line : function", and its icon marks a cartridge, the modules folder or a B2C module. Click a frame to open its line and variables
VariablesGrouped into Local, Closure and Global (collapsed). Empty scopes are hidden. dw objects expand up to 300 members per level
Jump to Source on a variableOpens the closest var declaration of that name above the paused line
Evaluate Expression, WatchesRun an expression in the paused frame. One that starts with a variable of another frame in the same file runs in that frame

A paused request doesn't time out while you look around. var variables read undefined until their line runs. An object the instance returns no members for shows one "SDAPI" row, "Salesforce Commerce Cloud Debugger: Empty response from the server"

Completion in Evaluate and Watches

Type a dot after an object in Evaluate Expression or a watch to list the members the live object has on the instance. Each shows its type and is marked "(intellij sfcc)"

  • Members whose names contain - are inserted in brackets, as ["name"]
  • Without a dot, the variables of the paused file are listed first

What the debugger doesn't do

  • Pause is disabled. Set a breakpoint instead
  • No exception breakpoints
  • Run to Cursor steps over one line
  • TypeScript sources aren't mapped. Set breakpoints in the uploaded JavaScript
  • No gutter shortcut for the configuration. Start it from the run widget or Run › Debug

With an AI agent

An agent connected to B2C MCP can drive this same session on the active connection: set breakpoints, wait for a stop, read variables and step, see Debugging with Agents

Troubleshooting

Message or symptomWhat to do
"No Valid B2C Commerce Connection. Please add B2C Commerce Connection"Add a connection and select it in the main toolbar, see Connections
"Config not valid. Please check your connection settings"The connection needs a hostname, an account and a code version, see Connections
"No cartridges found. Please add cartridges."Link a cartridge, see Cartridges & Modules
"[401][ClientIdRequiredException]. User is not authorized." with a note about text caseUser names are case-sensitive. Match the case, or turn on Use lowercase username on authentication requests in Connections
"Sandbox is down. This sandbox is currently stopped. Please start it and try again."Start the sandbox from On-Demand Sandboxes and debug again
"[Internal Server Error]. Request cannot be fulfilled because of an unexpected condition on the server.." or "[415][Unsupported Media Type]"Stop the session and start it again
"Debugger failed to initialize pipeline state before launch."Every session also starts the pipeline debugger. Check the connection and try again
Another message in brackets, such as [SomeException] ...The instance's own error text. Check the account's permissions on the instance
The IDE shows a stop a few seconds after the page started loadingExpected, the session checks for paused requests every 3.5 seconds
Breakpoints are never hitUpload the file again, check that the request runs that code, and that its cartridge is linked and on the site's cartridge path
"Plugin access is unavailable"Activate your subscription or seat, then restart the IDE, see Purchase & License

On this page