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
Before you start
| Needs | Why |
|---|---|
| An active connection with a valid account | The debugger signs in with the connection selected in the main toolbar, see Connections |
| At least one linked cartridge | Breakpoints outside linked cartridges and modules aren't sent, see Cartridges & Modules |
| The same code on the instance | Breakpoints match by file path and line. Upload the code or turn on Auto Upload |
| A valid license or trial | See 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
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]
| Line | When it appears |
|---|---|
| "Connected to" and the host | The 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:7 | The instance accepted a breakpoint, at session start and each time you add one |
| "Removed breakpoint" and the path | You removed or moved a breakpoint |
| "Disconnected from" and the host | You 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
| Option | What happens |
|---|---|
| Suspend turned off | The plugin logs what the breakpoint asks for and resumes the request |
| "Breakpoint hit" message | Printed in the console on every stop |
| Stack trace | Printed in the console on every stop |
| Remove once hit | Removed after its first stop |
| Disable until hitting the following breakpoint | Works as usual |
| Condition | Checked by the instance, so the breakpoint stops only when it is true |
| Evaluate and log | Evaluated in the stopped frame and printed in the console. With Suspend turned off, the request runs on |
While paused
| Control | What it does |
|---|---|
| Step Over, Step Into, Step Out | Step through the paused request |
| Resume | Continue until the next breakpoint |
| Frames | The 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 |
| Variables | Grouped into Local, Closure and Global (collapsed). Empty scopes are hidden. dw objects expand up to 300 members per level |
| Jump to Source on a variable | Opens the closest var declaration of that name above the paused line |
| Evaluate Expression, Watches | Run 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 symptom | What 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 case | User 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 loading | Expected, the session checks for paused requests every 3.5 seconds |
| Breakpoints are never hit | Upload 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 |