/wp-debug

description: Diagnose and fix WordPress block-theme failures — block validation errors, theme.json issues, missing patterns, DB template overrides, and PHP warnings.

/wp-debug

**Purpose:** Run a guided diagnostic workflow to identify and fix the root cause of a WordPress block theme problem. This command maps symptoms to specific root causes, provides step-by-step diagnosis, and offers to apply fixes directly to theme files.

When to Use

Trigger this command when:

• A block theme is producing an error message in the editor or on the front end
• Styles, colors, typography, or spacing are not applying correctly
• A pattern or template is missing from the Site Editor or inserter
• A file change had no visible effect
• The editor and front end look different
• Shortcodes, widget HTML, or ACF field values are not rendering in blocks
• PHP warnings or notices appear on the front end

When This Command Does NOT Apply

| Situation | Use Instead | |-----------|------------| | Converting static HTML/CSS to a block theme | `/convert-to-wp-theme` | | Plugin conflict causing a white screen or admin error | `/wp-plugin-theme` | | Hosting, server config, or database connection errors | Out of scope — contact hosting provider | | WP-CLI or SSH access denied | Out of scope — contact server admin | | Performance / Core Web Vitals issues | Out of scope — use `references/asset-optimization.md` |

---

Workflow

Step 1: Gather the Symptom

Ask the user:

> "Describe what you're seeing — paste the exact error message if there is one, or describe the behavior (e.g., 'blank page after I edited a block', 'my color palette shows gray instead of my brand colors', 'the hero pattern isn't showing in the inserter')."

If the user already included a symptom in their message with `/wp-debug`, skip asking and proceed directly to Step 2.

Accept any of these symptom forms:

• Pasted error message (verbatim text from browser or editor)
• Screenshot description ("I see a yellow warning banner in the editor")
• Behavioral description ("nothing changed after I updated the .html file")
• PHP log excerpt

---

Step 2: Map to Root-Cause Category

Use the decision tree below to classify the symptom. Output the matched category name before proceeding.

Decision Tree

Is there an error message in the block editor?
  YES → Does it say "This block contains unexpected or invalid content" or "Block recovery"?
          YES → Category 1: Block Validation Error
          NO  → Does it say "PHP Fatal error" or reference a missing file?
                  YES → Category 6: Assets Not Loading / Cache Issue
                  NO  → Category 5: Invalid Block-Support PHP Warning
  NO  →
    Is the problem visual (styles, colors, spacing, typography)?
      YES → Is WP_DEBUG generating PHP warnings related to block rendering?
              YES → Category 5: Invalid Block-Support PHP Warning
              NO  → Category 2: theme.json Silent Failure
    NO  →
      Is a pattern missing from the inserter or Site Editor?
        YES → Category 3: Pattern Not Showing
        NO  →
          Did you edit a .html template file but see no change on site?
            YES → Category 4: DB Template Overrides File
            NO  →
              Does it look right on front end but wrong in editor (or vice versa)?
                YES → Category 7: Editor Parity Gap
                NO  → Are shortcodes/widget HTML/ACF values not rendering as blocks?
                        YES → Category 8: Classic-to-Block Conversion Artifact
                        NO  → Run full diagnostic (all categories in order)

---

Step 3: Diagnose and Fix

Work through the matched category below. Output each section with its heading.

---

Category 1: Block Validation Error

**Symptoms:**

• "This block contains unexpected or invalid content"
• "Block recovery" prompt appears in editor
• Blank page after editing a block and saving
• Editor shows a red/yellow banner with "Attempt Block Recovery"

**Root Cause**

WordPress stores block content as HTML comments (`<!-- wp:block-name {...} -->`). The block editor validates this serialized markup against the registered block schema each time it loads. If the saved HTML does not match what the block's `save()` function would produce — due to a block update, a direct database edit, a plugin conflict writing to `post_content`, or copying markup across sites with different block versions — the editor considers the block "invalid" and refuses to render it.

**Diagnostic Steps**

1. Open the post or template in the browser console (F12 → Console) and look for: `Block validation: Block type "core/..." is not registered`. 2. Check if the block version mismatch is the cause:

   # Check your WordPress version
   wp core version

   # List all registered block types (output is long — grep for the failing block)
   wp eval 'foreach ( WP_Block_Type_Registry::get_instance()->get_all_registered() as $name => $block ) { echo $name . PHP_EOL; }'

3. Check `wp-content/debug.log` for serialization errors:

   grep -i "block" wp-content/debug.log | tail -30

4. Identify which post/template contains the invalid block:

   # Find posts containing a specific block that may be invalid
   wp post list --post_type=post,page,wp_template,wp_template_part \
     --format=table --fields=ID,post_title,post_type

5. View the raw `post_content` for the suspect post:

   wp post get <POST_ID> --field=post_content

**Fix**

Option A — Use Block Recovery (safest for individual posts):

1. Open the affected post in the block editor. 2. Click "Attempt Block Recovery" in the error banner. 3. If recovery renders correctly, save the post. This re-serializes the block to the current schema.

Option B — Convert to Classic block (when recovery fails):

1. In the error banner, click "Convert to Classic Block". 2. Copy the HTML content out of the Classic block