Magento Issue Debugger

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

``bash 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

• Adobe Commerce Troubleshooting
• Performance Best Practices
• Logging

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maxnorm
• Source: maxnorm/magento2-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.