Debugging

Script Debugger

Debug SFCC server-side JavaScript and DemandwareScript 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 in a browser and the IDE stops on that line with the call stack and live variables of the request

The SFCC debug configuration talks to the Script Debugger API: breakpoints, Step Over, Step Into, Step Out and Resume, with Local, Closure and Global scopes. Pause is not available, so set a breakpoint first

Before you start

NeedsWhy
An active connection with a valid accountThe debugger signs in with the account of the connection selected in the main toolbar, see Connections
At least one linked cartridgeBreakpoints are mapped to the instance through your linked cartridges, see Cartridges & Modules
The same code on the instanceUpload the code you debug, or turn on Auto Upload. Breakpoints match by file path and line, so local and remote files must be the same
A valid license or trialThe debugger is a paid feature, see Purchase & License

Start a session

Add the configuration

Open Run › Edit Configurations, click + and choose Salesforce B2C Commerce (SFCC). It is named "Salesforce B2C Commerce" and has nothing to fill in. Save it

Start it with Debug

Select the configuration in the run widget and click Debug . The configuration only debugs: Run stays unavailable for it on purpose, even though its settings page says to run it

Wait for the connection

The Debug tool window opens and the console prints "Connected to" with the host of your connection

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. The IDE stops on that line

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 and the session stops on the breakpoint

While paused

ControlWhat it does
Step Over, Step Into, Step OutMove through the code of the paused request
ResumeContinue until the next breakpoint
FramesThe call stack of the paused thread, shown as "Thread" and its ID. Click a frame to open its line and see its variables
VariablesGrouped into Local, Closure and Global. Expand dw objects to see their properties, up to 300 members per level
Evaluate Expression, WatchesRun an expression in the paused frame. Completion offers the members the instance reports for the live object, marked "(intellij sfcc)"

What the debugger doesn't do

The SFCC Script Debugger API is simpler than a local debugger, and some IDE controls do nothing or are missing:

  • Pause is disabled. Set a breakpoint to stop code
  • Breakpoint conditions aren't sent to the instance, so a conditional breakpoint stops every time
  • A breakpoint with Suspend turned off works, but Evaluate and log doesn't print anything
  • There are no exception breakpoints
  • Run to Cursor steps over one line instead of running to the cursor
  • TypeScript sources aren't mapped. Set breakpoints in the transpiled JavaScript that is uploaded
  • The configuration has no gutter shortcut. Start it from the run widget or Run › Debug

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 is missing a hostname, an account or a code version. Edit it in Connections
"No cartridges found. Please add cartridges."Link a cartridge, see Cartridges & Modules
"User is not authorized" and a note that your account must be in the same text case as on the instanceThe instance compares the user name case-sensitively. Change the account to the exact case, or turn on Use lowercase username on authentication requests in Connections
"Sandbox is down"The sandbox is stopped. Start it from On-Demand Sandboxes and debug again
"Debugger failed to initialize pipeline state before launch."Every session also starts the pipeline debugger. Check the connection and try again, see Pipeline debugging
Another message in brackets, such as [SomeException] ...That is the instance's own error text, passed through as it is. Check the account's permissions on the instance
Breakpoints are never hitUpload the file again, check that the request really runs that code, and make sure the cartridge is 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