Effective Magento 2 debugging starts with three things: developer mode enabled so errors are displayed and exceptions are not swallowed, the correct log files being read, and OPcache cleared after every code change. Without these three fundamentals, every other tool in this Magento 2 debugging guide will give you incomplete or misleading information.

Magento 2 debugging guide — complete toolkit from developer mode through Xdebug profiling to common error fixes

Magento 2 Debugging Guide: Enable Developer Mode First

The first step in any Magento 2 debugging guide session is confirming you are in developer mode. Default mode and production mode suppress errors, redirect exceptions to log files, and use cached templates — making debugging almost impossible. Developer mode shows full stack traces, disables the full-page cache, and recompiles templates on every request.

# Enable developer mode — first step in any Magento 2 debugging guide
bin/magento deploy:mode:set developer

# Verify current mode
bin/magento deploy:mode:show

# Clear all caches after switching mode
bin/magento cache:flush

# If blank screen persists after mode switch:
chmod -R 777 var/ generated/ pub/static/
bin/magento setup:di:compile

Magento 2 Debugging Guide: Reading the Right Log Files

Magento 2 writes different types of errors to different log files. This Magento 2 debugging guide covers the five most important logs and what each one tells you. All log files live in var/log/ relative to the Magento root.

# General application errors — start here in any Magento 2 debugging guide
tail -f var/log/system.log

# Exception stack traces — full PHP exceptions with file and line number
tail -f var/log/exception.log

# Scheduled task errors — cron job failures and timing issues
tail -f var/log/cron.log

# Custom module logs via PsrLogLoggerInterface
tail -f var/log/debug.log

# GraphQL resolver errors
tail -f var/log/graphql.log

# Live monitoring: watch all logs simultaneously
tail -f var/log/*.log

When following this Magento 2 debugging guide, always check exception.log first for a full stack trace. system.log contains lower-severity notices that often appear alongside a critical exception. To write from your own module to these logs, inject PsrLogLoggerInterface via DI and call $this->logger->error('message', ['context' => $data]).

Magento 2 Debugging Guide: Configure Xdebug for Step-Through Debugging

Xdebug is the most powerful tool in this Magento 2 debugging guide — it lets you pause execution at any line, inspect variable values, and step through call stacks. The configuration below uses Xdebug 3.x with VS Code, the most common setup for Magento 2 debugging in 2026.

; Magento 2 debugging guide: Xdebug 3.x configuration
zend_extension=xdebug

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.log_level=0

; Increase max nesting for Magento 2 debugging — Magento has deep call stacks
xdebug.max_nesting_level=256

; Increase these to avoid timeouts during Magento 2 debugging sessions
xdebug.connect_timeout_ms=2000

{
  "version": "0.2.0",
  "configurations": [
    {
      "name":        "Magento 2 Debugging Guide: Listen for Xdebug",
      "type":        "php",
      "request":     "launch",
      "port":        9003,
      "pathMappings": {
        "/var/www/html/magento": "${workspaceFolder}"
      }
    }
  ]
}

With this Magento 2 debugging guide Xdebug configuration, set a breakpoint in VS Code, open the store in your browser, and execution pauses at your breakpoint. You can inspect $this, local variables, and the full call stack. Essential for debugging plugin interceptors, observer callbacks, and resolver logic where var_dump() would be impractical.

Magento 2 Debugging Guide: Profile Performance with Blackfire

When the Magento 2 debugging guide problem is slow performance rather than an error, Blackfire is the tool. It profiles every function call, SQL query, and external HTTP request on a real page load and presents a flame graph showing exactly where time is spent.

# Install Blackfire PHP probe and agent
apt-get install blackfire
blackfire agent:start

# Profile a specific URL during Magento 2 debugging
blackfire curl https://your-staging-store.com/checkout/

# Profile a Magento CLI command — useful for Magento 2 debugging cron jobs
blackfire run php bin/magento indexer:reindex catalog_product_price

The Adobe Commerce testing and debugging documentation covers Magento’s built-in profiler. The Xdebug step debugging documentation covers all configuration options. The Blackfire Magento integration guide covers the full Blackfire setup for Magento 2 debugging. See our Magento 2 DI guide for how to inject LoggerInterface into your custom classes.

Magento 2 Debugging Guide: The 10 Most Common Errors and Fixes

This Magento 2 debugging guide section covers the errors you will encounter most frequently and their root causes:

• Blank white screen: OPcache serving stale bytecode after a deploy. Fix: bin/magento cache:flush then php -r "opcache_reset();" or restart PHP-FPM.
• Area code not set: Code running outside the Magento bootstrap context. Fix: ensure your script uses Bootstrap::create() or runs via bin/magento.
• Plugin class not found after DI compile: Namespace mismatch between di.xml and the actual class file path. Fix: verify PSR-4 autoload registration in composer.json.
• Interceptor compilation error: Plugin targeting a method that does not exist or is not public. Fix: check the target class method signature matches the plugin’s before/after/around parameter count.
• Memory exhausted during indexing: PHP memory limit too low for the catalogue size. Fix: increase memory_limit in php.ini to at least 2G for indexing operations.
• Session already started warning: Third-party code calling session_start() before Magento initialises the session. Fix: find and remove the direct session call — use Magento’s SessionManagerInterface instead.
• 404 on custom controller route: Module sequence or front name conflict. Fix: run bin/magento module:status and check etc/frontend/routes.xml front name uniqueness.

Magento 2 Debugging Guide: Enable Custom Logging in Your Module

For module-specific Magento 2 debugging, inject PsrLogLoggerInterface into your class and use structured log context arrays. This writes to var/log/debug.log by default and supports all PSR-3 severity levels.

<?php
use PsrLogLoggerInterface;

class MyService {
    public function __construct(
        private readonly LoggerInterface $logger
    ) {}

    public function process( int $id ): void {
        // Magento 2 debugging guide: structured context logging
        $this->logger->debug( 'Processing started', ['id' => $id] );
        try {
            // ... logic ...
            $this->logger->info( 'Processing complete', ['id' => $id, 'result' => 'ok'] );
        } catch ( Exception $e ) {
            $this->logger->error( 'Processing failed: ' . $e->getMessage(), [
                'id'        => $id,
                'exception' => $e,
            ]);
        }
    }
}

Frequently Asked Questions — Magento 2 Debugging Guide