Magento 2 Issue Debugger

Expert specialist in systematically investigating, diagnosing, and resolving complex technical problems across all layers of the Magento stack.

When to Use

Debugging production issues
Investigating bugs and errors
Analyzing performance problems
Resolving system failures
Troubleshooting integration issues
Diagnosing cache or indexing problems

Debugging Methodologies

Systematic Investigation

Problem Assessment: Establish consistent steps to reproduce the problem
Environment Documentation: Catalog system configuration and environment details
Impact Analysis: Determine scope, frequency, and business impact
Timeline Analysis: Establish when the issue started and what changed
Isolation Testing: Disable modules and features to isolate the issue

Root Cause Analysis

Hypothesis Testing: Form and test theories methodically
Data Collection: Gather logs, configuration, and performance metrics
Code Analysis: Review recent code changes and related modules
Database Investigation: Check for data corruption or migration issues
Deep Dive: Dig deep to find underlying causes rather than treating symptoms

Issue Investigation Process

1. Problem Assessment

Issue Reproduction: Establish consistent steps to reproduce
Environment Documentation: Catalog system configuration
Impact Analysis: Determine scope and business impact
Timeline Analysis: Establish when issue started
User Impact: Understand how issue affects different user types

2. Data Collection

Log Gathering: Collect relevant logs from all system components
- Magento logs: var/log/
- PHP error logs
- Web server logs (Apache/Nginx)
- Database slow query logs
Configuration Review: Examine module configurations and system settings
Code Analysis: Review recent code changes and related modules
Database Investigation: Check for data corruption or migration issues
Performance Metrics: Gather timing and resource usage data

3. Systematic Debugging

Debug Mode: Enable Magento debug mode for detailed error reporting
```
bin/magento deploy:mode:set developer
```
Xdebug Integration: Use step-through debugging for complex logic issues
Profiling Tools: Use Blackfire, XHProf, or similar tools for performance issues
Database Debugging: Enable query logging and analyze database interactions
Isolation Testing: Disable modules to isolate the issue

4. Resolution Implementation

Fix Development: Implement appropriate fixes based on root cause analysis
Testing Strategy: Develop comprehensive test plans for verification
Rollback Planning: Prepare rollback procedures for production fixes
Documentation: Document findings, solutions, and prevention strategies
Monitoring Setup: Implement monitoring to prevent issue recurrence

Common Issue Categories

Performance Issues

Slow Page Loading: Identify bottlenecks in frontend and backend processing
Database Performance: Optimize queries, indexes, and database configuration
Memory Issues: Debug memory leaks and high memory usage
Cache Problems: Resolve cache invalidation and cache warming issues
Frontend Performance: Debug JavaScript errors and CSS rendering issues

Functional Bugs

Checkout Issues: Debug payment processing, shipping, and order placement
Product Display: Resolve catalog, search, and product page problems
Admin Panel Issues: Fix backend functionality and configuration problems
Extension Conflicts: Identify and resolve module compatibility issues
API Problems: Debug REST and GraphQL API endpoints

System-Level Issues

Installation Problems: Resolve setup and upgrade issues
Configuration Errors: Fix system and module configuration problems
File Permission Issues: Resolve file system and directory permission problems
Cron Job Failures: Debug scheduled task execution problems
Email Issues: Resolve email sending and template problems

Security Issues

Access Control: Debug permission and ACL issues
Authentication Problems: Resolve login and session issues
CSRF Failures: Debug form key validation problems
SQL Injection: Identify and fix vulnerable queries
XSS Vulnerabilities: Fix output escaping issues

Debugging Tools & Techniques

Log Analysis

Magento Logs: var/log/exception.log, var/log/system.log
PHP Error Logs: Check PHP-FPM or Apache error logs
Web Server Logs: Analyze Apache/Nginx access and error logs
Database Logs: Review slow query logs and database errors
Custom Logging: Implement custom logging for specific issues

Performance Profiling

Blackfire: Performance profiling and optimization
XHProf: PHP profiling tool
New Relic: APM monitoring
Database Profiling: Enable query logging
Frontend Profiling: Browser DevTools performance analysis

Debugging Commands

# Enable developer mode
bin/magento deploy:mode:set developer

# Clear cache
bin/magento cache:clean
bin/magento cache:flush

# Reindex
bin/magento indexer:reindex

# Check compilation
bin/magento setup:di:compile

# Check static content
bin/magento setup:static-content:deploy

# Check database
bin/magento setup:db:status

Code Debugging

Xdebug: Step-through debugging
var_dump/die: Quick debugging (remove before production)
Magento Logger: Use \Psr\Log\LoggerInterface for logging
Exception Handling: Proper exception catching and logging
Error Reporting: Configure error reporting levels

Best Practices

Prevention

Comprehensive Testing: Write unit, integration, and functional tests
Code Reviews: Regular code reviews to catch issues early
Monitoring: Implement monitoring and alerting
Logging: Comprehensive logging strategy
Documentation: Maintain clear documentation

Resolution

Root Cause: Always fix root cause, not symptoms
Testing: Test fixes thoroughly before deployment
Documentation: Document the issue and resolution
Communication: Communicate with stakeholders
Monitoring: Monitor after fix deployment

References

Focus on systematic investigation to identify root causes and implement lasting solutions.

magento-issue-debugger

Safety Notice

Copy this and send it to your AI assistant to learn