---
description: SFCC debugging and error investigation workflows
globs: []
alwaysApply: false
---
# SFCC Debugging and Error Investigation
Use this rule when investigating errors, performance issues, or debugging SFCC applications.
## Mandatory MCP Tool Sequence for Debugging
### 🚨 For Active Errors/Issues (ALWAYS start here):
1. `mcp_sfcc-dev_summarize_logs` - Get system health overview and error counts
2. `mcp_sfcc-dev_get_latest_error` - Check most recent critical errors
3. `mcp_sfcc-dev_search_logs` with pattern: [specific error message] - Find error instances
### ⚠️ For Performance Issues:
1. `mcp_sfcc-dev_get_latest_warn` - Check performance warnings first
2. `mcp_sfcc-dev_search_logs` with pattern: "timeout" or "slow" or "performance"
3. `mcp_sfcc-dev_search_best_practices` with query: "performance" - Get optimization patterns
4. `mcp_sfcc-dev_get_best_practice_guide` with guideName: "performance" - Comprehensive guide
### 🔍 For Transaction Tracing:
1. `mcp_sfcc-dev_search_logs` with pattern: [transaction-id] - Find transaction entries
2. `mcp_sfcc-dev_search_logs` with pattern: [customer-id] - Track customer journey
### 📊 For System Health Assessment:
1. `mcp_sfcc-dev_summarize_logs` - Overall system status
2. `mcp_sfcc-dev_list_log_files` - Check log availability and sizes
3. `mcp_sfcc-dev_get_log_file_contents` - Read specific log files (with size limits: maxBytes, tailOnly options)
4. `mcp_sfcc-dev_get_latest_info` - Review normal operations
5. `mcp_sfcc-dev_get_latest_debug` - Detailed execution traces (when needed)
### 🔧 For Job Analysis and Debugging:
1. `mcp_sfcc-dev_get_latest_job_log_files` - Get recent job log files
2. `mcp_sfcc-dev_search_job_logs_by_name` - Find logs for specific jobs
3. `mcp_sfcc-dev_get_job_log_entries` - Get job entries by level (error, warn, info, debug, all)
4. `mcp_sfcc-dev_search_job_logs` - Search for patterns in job logs
5. `mcp_sfcc-dev_get_job_execution_summary` - Get comprehensive execution summary with timing and status
**Job Debugging Use Cases:**
- Custom job steps failing with specific errors
- Job performance issues and bottlenecks
- Job step execution order and timing problems
- Custom logging from job steps
- Job completion status and statistics
### 🚀 For Deployment and Code Version Issues:
1. `mcp_sfcc-dev_get_code_versions` - Check available code versions on instance
2. `mcp_sfcc-dev_activate_code_version` - Perform code-switch fix for SCAPI endpoints/jobs
**Common Code-Switch Fix Scenarios:**
- New SCAPI endpoints not accessible after deployment
- Custom jobs not appearing in Business Manager
- Hook registrations not taking effect
- Custom object definitions not recognized
## MCP-Enhanced Error Handling Code Patterns
Get patterns from MCP first, then implement:
```javascript
// BEFORE writing this code, use:
// mcp_sfcc-dev_search_best_practices with query: "error"
// mcp_sfcc-dev_get_best_practice_guide with guideName: "security"
try {
// Business logic
} catch (e) {
var Logger = require('dw/system/Logger').getLogger('category', 'subcategory');
// Include correlation ID for MCP log tracing
var correlationId = request.getRequestId() || require('dw/util/UUIDUtils').createUUID();
Logger.error('Operation failed in [context] - Correlation: {0} - Error: {1}', correlationId, e.message);
Logger.debug('Stack trace - Correlation: {0} - Stack: {1}', correlationId, e.stack);
// Return meaningful error response
return {
success: false,
error: 'OPERATION_FAILED',
message: 'Unable to complete operation',
correlationId: correlationId
};
}
```
## MCP-Driven Debugging Workflow
**Step 1: System Overview**
```
Use: mcp_sfcc-dev_summarize_logs
Purpose: Get error counts, warning levels, system health snapshot
```
**Step 2: Error Investigation**
```
Use: mcp_sfcc-dev_get_latest_error (limit: 5)
Purpose: Identify most recent critical issues
```
**Step 3: Best Practice Consultation**
```
Use: mcp_sfcc-dev_search_best_practices with query: [relevant topic]
Purpose: Get SFCC-specific debugging and fix patterns
```
## Performance Investigation Checklist
Before investigating performance issues, ALWAYS use:
- [ ] `mcp_sfcc-dev_get_latest_warn` - Check performance warnings
- [ ] `mcp_sfcc-dev_search_best_practices` with query: "performance"
- [ ] `mcp_sfcc-dev_get_best_practice_guide` with guideName: "performance"
Then check:
- [ ] Database query efficiency (verify with MCP performance guide)
- [ ] API call patterns (validate against SFCC best practices)
- [ ] Caching strategies (compare with MCP recommendations)
- [ ] Memory usage patterns (check against SFCC guidelines)
- [ ] Transaction boundaries (verify with MCP transaction patterns)
- [ ] Unnecessary loops or iterations (optimize per MCP patterns)
## MCP Log Search Patterns
**For Errors:**
```
mcp_sfcc-dev_search_logs with pattern: "ERROR" and logLevel: "error"
mcp_sfcc-dev_search_logs with pattern: "Exception" and logLevel: "error"
mcp_sfcc-dev_search_logs with pattern: "Failed" and logLevel: "error"
```
**For Performance Issues:**
```
mcp_sfcc-dev_search_logs with pattern: "timeout"
mcp_sfcc-dev_search_logs with pattern: "slow"
mcp_sfcc-dev_search_logs with pattern: "performance"
```
**For Security Issues:**
```
mcp_sfcc-dev_search_logs with pattern: "authentication"
mcp_sfcc-dev_search_logs with pattern: "authorization"
mcp_sfcc-dev_search_logs with pattern: "security"
```
## MCP Log File Analysis
**When to Use `mcp_sfcc-dev_get_log_file_contents`:**
- After `mcp_sfcc-dev_list_log_files` identifies specific files of interest
- When you need complete context around an error (not just recent entries)
- For analyzing large log files with size constraints
**Usage Patterns:**
```
# Read specific error log file completely
mcp_sfcc-dev_get_log_file_contents with filename: "error-2024-01-15.log"
# Read first 1MB of large log for pattern analysis
mcp_sfcc-dev_get_log_file_contents with filename: "debug.log", maxBytes: 1048576, tailOnly: false
# Read last 500KB for most recent activity
mcp_sfcc-dev_get_log_file_contents with filename: "error.log", maxBytes: 512000, tailOnly: true
```
## NEVER Debug Without MCP
- ❌ Don't guess at error causes - use `mcp_sfcc-dev_search_logs` for pattern analysis
- ❌ Don't implement fixes without consulting `mcp_sfcc-dev_search_best_practices`
- ❌ Don't trace issues manually - use `mcp_sfcc-dev_search_logs` with correlation IDs
- ❌ Don't assume system health - always start with `mcp_sfcc-dev_summarize_logs`
