WordPress Troubleshooting Checklist: How to Isolate the Real Root Cause

Posted on by

WordPress Troubleshooting Checklist: Areas to Check First, Commands to Run, and How to Isolate the Real Root Cause

When a WordPress website starts behaving strangely, the biggest mistake is jumping to conclusions too early. A problem that looks like a theme issue may actually be caused by a plugin. A Gutenberg editor issue may be caused by security rules in .htaccess. A broken admin area may look like a CSS problem but actually be a blocked load-styles.php request.

The only reliable way to solve WordPress problems is to troubleshoot in a structured way.

In this guide, I will walk through a practical troubleshooting framework for WordPress sites, especially for problems like:

  • wp-admin looks broken after login
  • Gutenberg editor formatting like Bold does not work
  • public site is fine but admin/edit mode is broken
  • changing theme does not help
  • disabling browser cache does not solve the issue
  • plugin conflicts are suspected
  • security plugins or rewrite rules are interfering

This tutorial also includes real commands you can run on a Linux/XAMPP server using terminal and WP-CLI.

Why a structured troubleshooting process matters

WordPress issues often have overlapping symptoms.

For example:

  • a theme problem can affect styling
  • a plugin problem can affect editing
  • a security rule can block admin assets
  • a cache rule can make the browser show old broken behavior
  • a must-use plugin can keep loading even when all plugins appear disabled

That is why random trial-and-error wastes time. A clear step-by-step process helps you isolate the real culprit faster.

Step 1: Observe the scope of the problem

Before running commands, ask these questions:

1. Is the public website broken, or only wp-admin?

This is the first major split.

  • If public site is broken, suspect theme, plugins, permissions, or core issues
  • If public site is fine but admin is broken, suspect admin CSS/JS, plugins, security rules, or editor conflicts

2. Is the issue only on one post/page, or everywhere?

Test:

  • a brand new post
  • a different existing post
  • the same post in another browser

If the issue happens only on one post, it may be bad block content or broken markup in that post.

3. Is the issue visual only, or functionality too?

Example:

  • toolbar missing but Cmd+B still works → likely UI/CSS issue
  • toolbar missing and Cmd+B does not work → likely plugin/editor logic issue

That distinction is very important.

Step 2: Check browser-level issues first

Sometimes the problem is not on the server at all.

Areas to check

  • cached CSS/JS
  • site storage/local storage
  • extensions like Grammarly, ad blockers, dark mode tools
  • browser-specific editor corruption

What to do

Open in Incognito

If the issue disappears in Incognito, it is likely:

  • browser cache
  • extension conflict
  • site data corruption

Hard refresh

On Mac:

Cmd + Shift + R

Clear site data in Chrome

  • open the website
  • click the icon near the address bar
  • Site settings
  • Clear data

If the issue still happens in Incognito and another browser, then move on to server-side isolation.

Step 3: Check file ownership and permissions

If files were manually copied, edited, or moved as root, permissions and ownership should be verified.

Check WordPress root ownership

cd /opt/lampp/htdocs/devopsschool/blog
ls -lrt

Check ownership of key WordPress folders

stat -c '%U:%G %a %n' wp-admin wp-includes wp-content wp-config.php

Find anything not owned by the correct web user

find . \( ! -user www-data -o ! -group www-data \) -ls | head -50

Find any files touched by root

find . -user root -ls | head -50

Normalize ownership and permissions

chown -R www-data:www-data .

find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;

chmod 640 wp-config.php

What good output usually looks like

  • directories: 755
  • files: 644
  • wp-config.php: 640 is fine
  • owner/group: www-data:www-data or whatever your Apache/PHP user uses

If ownership and permissions are already correct, stop spending time there and move on.

Step 4: Rule out theme issues

Many WordPress problems are blamed on themes too early.

First question

Does the same problem happen with another theme?

List installed themes

wp theme list --allow-root

Activate a default theme

wp theme activate twentytwentyfour --allow-root

or

wp theme activate twentytwentythree --allow-root

What the result means

  • if the issue disappears on a default theme, theme or theme-related customization is involved
  • if the issue remains across multiple themes, the theme is probably not the main problem

A very important learning here is this:

If the same issue happens with many themes, stop blaming the theme.

Step 5: Check if wp-admin assets are loading correctly

If logged-in admin looks broken but the public site looks fine, this is one of the most important areas to check.

Symptoms

  • wp-admin looks like plain HTML
  • left menu is unstyled
  • post editor looks broken
  • buttons or controls are missing
  • customizer or editor is visually broken

This usually means WordPress admin CSS/JS is not loading.

Check .htaccess

cd /opt/lampp/htdocs/devopsschool/blog
ls -la .htaccess wp-admin/.htaccess
sed -n '1,200p' .htaccess
[ -f wp-admin/.htaccess ] && sed -n '1,200p' wp-admin/.htaccess

Real-world example

A security plugin had written rules into .htaccess that blocked:

  • wp-admin/load-styles.php
  • wp-admin/load-scripts.php

That made wp-admin appear broken even though WordPress core and themes were fine.

Example of a dangerous block

# BEGIN WP CERBER GROOVE
RewriteCond %{REQUEST_URI} ^(.*)wp-admin/+load-scripts\.php$ [OR,NC]
RewriteCond %{REQUEST_URI} ^(.*)wp-admin/+load-styles\.php$ [NC]
RewriteCond %{HTTP_COOKIE} !cerber_groove_x_...
RewriteRule (.*) - [R=403,L]
# END WP CERBER GROOVE

Fix by removing the block

cp .htaccess .htaccess.bak.$(date +%F-%H%M%S)
sed -i '/# BEGIN WP CERBER GROOVE/,/# END WP CERBER GROOVE/d' .htaccess

That kind of rule can break wp-admin even if the public site is fine.

Step 6: Verify WordPress core integrity

If you suspect core files are corrupted, do not guess.

Verify core checksums

wp core verify-checksums --allow-root

What this means

  • if verification passes, WordPress core files are likely intact
  • if it fails, repair core

Repair core files without touching themes/plugins

wp core download --skip-content --force --allow-root

This is a safe and clean way to restore WordPress core files.

Step 7: Disable all plugins and test again

This is one of the most powerful steps.

If the issue disappears when all plugins are disabled, then you know with high confidence it is a plugin conflict.

Deactivate all plugins

wp plugin deactivate --all --allow-root

Test again

After disabling all plugins:

  • open a brand new post
  • add a Paragraph block
  • type text
  • select a word
  • test Bold
  • test Cmd+B

If the issue disappears, the problem is plugin-related.

Step 8: Do not forget must-use plugins

One common mistake is thinking all plugins are disabled when they are not.

Must-use plugins in wp-content/mu-plugins still load even after normal plugins are deactivated.

Check must-use plugins

ls -la wp-content/mu-plugins/

Disable one temporarily

mv wp-content/mu-plugins/aaa-wp-cerber.php wp-content/mu-plugins/aaa-wp-cerber.php.off

This is extremely important because MU plugins can silently continue affecting admin or editor behavior.

Step 9: Identify the culprit plugin with binary testing

Once you know plugins are the issue, do not reactivate everything randomly.

Use a structured process.

List all plugins

wp plugin list --allow-root

Reactivate in batches

Example batch:

wp plugin activate classic-editor code-block-pro syntax-highlighting-code-block luckywp-table-of-contents pdf-embedder seo-by-rank-math ad-inserter --allow-root

Another batch:

wp plugin activate wpdiscuz youtube-embed-plus yotuwp-easy-youtube-embed simple-author-box simple-banner simple-blog-stats wp-rss-aggregator wp-sitemap-page google-sitemap-generator --allow-root

If one batch causes the issue and another does not, you have narrowed the culprit to one group.

Then activate one by one

wp plugin activate disable-xml-rpc-api --allow-root
wp plugin activate creame-whatsapp-me --allow-root
wp plugin activate limit-login-attempts-reloaded --allow-root
wp plugin activate merpress --allow-root
wp plugin activate plagiarism-checker-by-sst --allow-root
wp plugin activate wp-security-audit-log --allow-root
wp plugin activate wp-fastest-cache --allow-root
wp plugin activate wp-mail-smtp --allow-root
wp plugin activate wp-paypal --allow-root
wp plugin activate wps-hide-login --allow-root

Test after each activation.

This is exactly how the real culprit can be found.

Step 10: Example of a real plugin culprit

In this case, the actual plugin causing the Gutenberg Bold issue was:

plagiarism-checker-by-sst

Symptom

  • Bold formatting in Gutenberg did not work
  • multiple themes were tested
  • admin styling issue was fixed separately
  • once all plugins were disabled, Bold started working
  • when plugins were reactivated one by one, the issue returned when plagiarism-checker-by-sst was enabled

Fix

Keep it disabled:

wp plugin deactivate plagiarism-checker-by-sst --allow-root

This is a classic example of a plugin interfering with Gutenberg rich-text functionality.

Step 11: Check editor-related code in themes and plugins

If the problem looks like a Gutenberg/editor issue, search code for admin/editor hooks.

Search theme/editor hooks

grep -RniE "admin_enqueue_scripts|enqueue_block_editor_assets|enqueue_block_assets|customize_register|admin_head|login_enqueue_scripts|block_editor_settings_all" wp-content/themes

Search plugin/editor hooks

grep -RniE "admin_enqueue_scripts|enqueue_block_editor_assets|wp_enqueue_script|wp_enqueue_style|gutenberg|block_editor|unregisterFormatType|allowedFormats|contenteditable|tinymce|execCommand" wp-content/plugins

Search for suspicious CSS hiding toolbar behavior

grep -RniE "components-toolbar|rich-text|toolbar|display:\s*none|visibility:\s*hidden|opacity:\s*0|pointer-events:\s*none" wp-content

This helps you catch:

  • editor CSS pollution
  • hidden toolbar buttons
  • disabled text formats
  • scripts injected into admin screens

Step 12: Use browser DevTools when necessary

When the issue is still unclear, browser tools can show exactly what is happening.

Network tab

Look for:

  • load-styles.php
  • load-scripts.php
  • failed CSS/JS requests
  • 403 / 404 / 500 errors

Console tab

Look for red errors involving:

  • wp.richText
  • wp.blockEditor
  • format-library
  • custom plugin or theme JS files

If CSS is not loading or JS errors appear, that often points directly to the cause.

Step 13: Debug WordPress more safely

Temporarily add these to wp-config.php:

define( 'CONCATENATE_SCRIPTS', false );
define( 'SCRIPT_DEBUG', true );
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Why this helps

  • SCRIPT_DEBUG loads non-minified JS/CSS
  • CONCATENATE_SCRIPTS can bypass combined loader issues
  • WP_DEBUG_LOG captures warnings/errors to log files

This is especially useful when admin assets are failing.

Step 14: Suggested troubleshooting order

Here is the order I recommend for real-world WordPress troubleshooting:

1. Observe the scope

  • public only?
  • admin only?
  • single post only?
  • browser-specific?

2. Test browser basics

  • incognito
  • hard refresh
  • clear site data
  • disable extensions

3. Check permissions and ownership

  • owner/group
  • 755 dirs
  • 644 files
  • no stray root-owned files

4. Switch to a default theme

  • confirm whether the issue is theme-related

5. Check .htaccess

  • especially security rules affecting wp-admin

6. Verify core

  • run wp core verify-checksums

7. Disable all plugins

  • test cleanly

8. Check MU plugins

  • wp-content/mu-plugins

9. Reactivate plugins in batches

  • then one by one

10. Search code

  • admin/editor hooks
  • CSS hiding controls
  • Gutenberg format restrictions

11. Use DevTools

  • Network
  • Console

This order saves a lot of time.

Final lessons learned

This troubleshooting journey highlights a few important truths:

1. One symptom can hide multiple problems

There may be more than one issue at the same time.

2. Admin-only problems are not always theme problems

If public view is fine, look at admin CSS/JS, plugins, and rewrite rules.

3. Security plugins can leave rules behind

Even after disabling them, their .htaccess changes may remain active.

4. MU plugins are easy to forget

A must-use plugin can continue affecting the site even when all regular plugins are off.

5. Plugin conflicts are often the real culprit

In this case, plagiarism-checker-by-sst was the root cause of the Gutenberg Bold problem.

6. Structured troubleshooting beats guessing

The faster you isolate scope, test variables one by one, and observe results, the faster you find the real cause.

Useful command summary

Theme checks

wp theme list --allow-root
wp theme activate twentytwentyfour --allow-root

Plugin checks

wp plugin list --allow-root
wp plugin deactivate --all --allow-root
wp plugin activate plugin-slug --allow-root

MU plugin checks

ls -la wp-content/mu-plugins/
mv wp-content/mu-plugins/plugin.php wp-content/mu-plugins/plugin.php.off

Core verification

wp core verify-checksums --allow-root
wp core download --skip-content --force --allow-root

Ownership and permissions

stat -c '%U:%G %a %n' wp-admin wp-includes wp-content wp-config.php
find . \( ! -user www-data -o ! -group www-data \) -ls | head -50
chown -R www-data:www-data .
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod 640 wp-config.php

.htaccess inspection

sed -n '1,200p' .htaccess

Search theme/plugin hooks

grep -RniE "admin_enqueue_scripts|enqueue_block_editor_assets|enqueue_block_assets|customize_register" wp-content

Conclusion

If you troubleshoot WordPress issues without a checklist, you will often waste hours chasing the wrong cause. But if you follow a structured path — browser, permissions, themes, .htaccess, core, plugins, MU plugins, code hooks, and DevTools — you can isolate even very tricky issues.

In this case, what looked like a theme/editor issue turned out to be a combination of:

  • blocked wp-admin asset loading from security rewrite rules
  • and a Gutenberg conflict caused by plagiarism-checker-by-sst

That is exactly why systematic troubleshooting matters.