wp-debugging

WordPress Debugging Methodology

Systematic debugging for WordPress and PHP. Four phases: root cause investigation, pattern analysis, hypothesis testing, implementation. No guessing. No shotgun fixes.

---

Critical Rules

• Never apply a fix without identifying the root cause. Guessing wastes time and introduces new bugs.
• Enable WP_DEBUG first. Every debugging session starts by enabling debug mode. No exceptions.
• Check error logs before guessing. The answer is almost always in debug.log, the PHP error log, or the server error log. Read them.
• One change at a time. If you change two things and the bug disappears, you do not know which change fixed it. Revert one and verify.
• Always test in staging. Never debug production by pushing untested changes to it. Clone the environment or use wp-env.
• Document what you find. Leave a comment explaining the root cause at the fix site. Future developers (including you) will thank you.

---

Phase 1: Root Cause Investigation

Before forming any hypothesis, gather evidence. This phase is about observation, not action.

1.1 Enable WordPress Debug Mode

Add these constants to wp-config.php above the /* That's all, stop editing! */ line:

// Enable debug mode — shows PHP errors and WordPress deprecation notices.
define( 'WP_DEBUG', true );

// Log errors to wp-content/debug.log instead of displaying on screen.
define( 'WP_DEBUG_LOG', true );

// Do NOT display errors on the frontend (security risk on production).
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Load unminified versions of core CSS and JS files (useful for debugging core/Gutenberg).
define( 'SCRIPT_DEBUG', true );

Verify debug mode is active:

wp eval 'echo WP_DEBUG ? "WP_DEBUG is ON" : "WP_DEBUG is OFF";'

1.2 Read the Debug Log

# View the last 50 lines of the WordPress debug log.
tail -50 wp-content/debug.log

# Follow the log in real time while reproducing the bug.
tail -f wp-content/debug.log

# Search for fatal errors.
grep -i "fatal error" wp-content/debug.log | tail -20

# Search for a specific plugin's errors.
grep "my-plugin" wp-content/debug.log | tail -20

# Clear the log before a fresh reproduction attempt.
> wp-content/debug.log