Troubleshooting

Quick checks

• Node.js 18+ is installed
• dw.json exists and has chmod 600 permissions
• The SFCC sandbox is active and reachable

Quick test Run `npx -y sfcc-dev-mcp --debug` to verify the server starts without errors.

Server will not start

node --version
npx -y sfcc-dev-mcp --debug

Node.js version mismatch

node --version
nvm install 18 && nvm use 18

If you work with older SFRA/SiteGenesis projects, set a higher default Node version for MCP:

nvm alias default 18
nvm use 12.22.6

File permissions

chmod 600 dw.json
ls -la dw.json

Package installation

npm install -g sfcc-dev-mcp
npx -y sfcc-dev-mcp --version

Authentication issues

• Verify hostname, username, and password
• Regenerate client-id and client-secret if OCAPI calls fail
• Confirm OCAPI resources in Business Manager match the configuration page

Test connectivity

curl -I https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com

Regenerate API credentials

curl -X POST \
	https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/dw/oauth2/access_token \
	-H "Content-Type: application/x-www-form-urlencoded" \
	-d "grant_type=client_credentials&client_id=NEW_ID&client_secret=NEW_SECRET"

Log tools return no data

• Test WebDAV access directly:

curl -u "username:password" https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/Logs/

• Ensure logs exist for the requested date

Wrong date format

get_latest_error({ date: "20241218" })

System object tools failing

• Confirm Data API resources include definition_search endpoints (POST)
• Ensure client-id matches the OCAPI client in Account Manager

Required Data API resources

{
	"_v": "23.2",
	"clients": [{
		"client_id": "YOUR_CLIENT_ID",
		"resources": [
			{ "resource_id": "/system_object_definitions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/system_object_definitions/*", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/system_object_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/system_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/system_object_definitions/*/attribute_group_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/custom_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/site_preferences/preference_groups/*/*/preference_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/code_versions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
			{ "resource_id": "/code_versions/*", "methods": ["get", "patch"], "read_attributes": "(**)", "write_attributes": "(**)" }
		]
	}]
}

Job log tools issues

Job log access

curl -u "username:password" \
	https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/Logs/jobs/

Minimal health flow

aegis query search_job_logs_by_name 'jobName:MyJob|limit:3'
aegis query get_job_log_entries 'jobName:MyJob|limit:40'
aegis query get_job_execution_summary 'jobName:MyJob'

AI client not connecting

Validate MCP config

python -m json.tool claude_desktop_config.json
npx -y sfcc-dev-mcp --debug

Auto-discovery not working

No tools after adding dw.json

• Ensure your client supports MCP roots/list (VS Code/Copilot/Cursor do).
• Re-open the workspace after adding dw.json.
• If your client does not support workspace roots, pass --dw-json explicitly.

Debug logging

npx -y sfcc-dev-mcp --debug
npx -y sfcc-dev-mcp --debug false --dw-json /path/to/dw.json

Log file locations

• macOS: /var/folders/{user-id}/T/sfcc-mcp-logs/
• Linux: /tmp/sfcc-mcp-logs/
• Windows: %TEMP%\sfcc-mcp-logs\

node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"

Getting help

Collect diagnostic data and remove secrets before sharing:

node --version
npm --version
npm list sfcc-dev-mcp

AI client not connecting

• Validate your MCP config file JSON
• Restart the client after changes
• Ensure the MCP server command uses npx and an absolute dw.json path