Reading the debug log
Your site has been writing you letters. Here's how to read them.
Every mysterious WordPress symptom — the intermittent white screen, the form that fails on Tuesdays, the slowly corrupting checkout — narrates itself in the debug log, if anyone turns the log on and can read the handwriting. This page teaches both: enabling it safely, and knowing which lines matter.
Same-day diagnosis. Flat quote before any fix.
What’s actually happening
WordPress ships with a flight recorder that's off by default: set WP_DEBUG and WP_DEBUG_LOG in wp-config.php and every PHP complaint gets written to wp-content/debug.log with a timestamp, a message, a file path, and a line number. The file path is the payload — /plugins/some-plugin/ in the trail convicts that plugin; /themes/yours/ convicts the theme; repeated identical entries at matching timestamps convert 'the site acts weird sometimes' into 'this file, this line, every time a form submits.'
Reading it is mostly triage vocabulary. Fatal errors are the site actually dying — these are your white screens, and the log names the killer. Warnings are misbehavior in progress: things half-working, worth attention. Deprecated notices are aging code being warned about the future — today's noise, but a census of which plugins are drifting toward abandonment. The skill is severity-sorting plus one discipline: on a live site, log to file, never display to screen (WP_DEBUG_DISPLAY false) — errors printed onto public pages leak server paths to the world and look worse than the bug did.
The usual causes, ranked
After twenty-seven years of these calls, the odds are well mapped. Start at the top.
Fatals — the site's actual deaths
'PHP Fatal error' lines with a file path: each one is a white screen or dead feature, signed by its author. The first lines worth reading.
Warning swarms
Recurring warnings from one file — the signature of a feature limping. Volume and repetition matter more than any single entry.
Deprecation drizzle
Deprecated-function notices, usually harmless today — but a plugin generating pages of them is telling you its maintenance stopped years ago.
Database complaint clusters
'WordPress database error' entries — a different organ complaining, often the earliest sign of corruption or a misbehaving query.
What you can safely try first
Nothing below can make things worse — that’s the selection criterion. Anything riskier belongs in professional hands, on a backup.
- 1
Turn the recorder on, safely
In wp-config.php: WP_DEBUG true, WP_DEBUG_LOG true, WP_DEBUG_DISPLAY false. That last false is the safety catch for a public site — log to file, never to screen.
- 2
Reproduce the problem once
Trigger the symptom, note the clock time, open wp-content/debug.log and read the entries at that timestamp. You're not reading the whole log — you're reading the minute that matters.
- 3
Extract the file paths
Every entry names its source. The directory after /plugins/ or /themes/ is your suspect list, ranked by frequency. That list is the diagnosis, even if the fix isn't yours to make.
Stop and call when…
- The log names a fatal in code you depend on — reading the letter and performing the surgery are different trades
- Entries reference core files — usually an innocent plugin calling core badly, and tracing that chain is real diagnosis
- The log is growing by megabytes daily — that volume is itself a finding, and a performance tax, needing systematic cleanup
From there it’s our job: same-day look, flat quote, and the $229 flat repair covers most cases of exactly this.
Single Error Fix — buy it now, skip the hunt.
One error, hunted down and fixed — 500s, white screens, redirect loops, broken pages.
Covers one specific error or broken behavior on one site. Diagnosis, the fix, and a plain-English note on what happened. If we can't fix it, you get a full refund.
Questions we hear a lot.
Is it safe to leave debug logging on all the time?
Logging to file with display off is safe and, frankly, good hygiene for a site under active care — with one caveat: the file grows, and a noisy site can write serious megabytes. The unsafe variant is WP_DEBUG_DISPLAY on a public site, which prints errors — server paths included — onto pages for everyone. File on, display off, rotate occasionally: that's the professional posture.
I opened the log and it's thousands of lines. Where do I start?
Search, don't scroll: 'Fatal' first (actual deaths), then the timestamp of your last symptom (the minute that matters), then count repeated entries (frequency equals significance). Ninety percent of a big log is deprecation drizzle you can ignore today. The signal is fatals, clusters, and whatever wrote at the moment things broke.
What does the $229 diagnosis include?
Logging enabled safely if it isn't, the log read professionally — fatals traced, clusters attributed, the noise separated from the signal — the primary culprit fixed where it's a repair-scale item, and a written summary of what your site has been trying to tell you, including the aging-plugin census. You keep the letters; we translate them.
Related symptoms & help
Errors travel in packs. If this one visited, check its friends.
Your site's letters, translated same-day.
Send the symptom, get a same-day look and a flat quote from the developer who's fixed this exact thing more times than either of us can count.