Troubleshooting Child Themes
warning
Always keep a rollback command ready (wp theme activate generatepress). Fix issues on staging first when possible.
When to Use This Page
| Category | Typical issues | Primary tool |
|---|---|---|
| Activation | wrong folder/header | WP-CLI + style.css |
| Styling | enqueue order, cache | browser + cache purge |
| Hooks | wrong hook name | grep + small test output |
| Overrides | wrong path, outdated files | filesystem + diff |
| Errors | PHP fatal, warnings | /usr/local/lsws/logs/error.log |
What This Flow Covers
- Child themes are the most common place custom bugs live.
- A systematic workflow prevents random guessing.
- Fast rollback reduces downtime.
How It Works
Most issues reduce to one of:
- WP is not using the child theme
- WP cannot link to the parent theme
- assets are not loading (or cache is stale)
- PHP has an error
Diagnostic Flow
Step 1: Confirm Active Theme
confirm-active-theme.sh
cd /var/www/html
wp option get stylesheet
wp option get template
wp theme list | grep generatepress
Step 2: Verify style.css Header
verify-style-header.sh
cd /var/www/html
grep -n "^Theme Name:\|^Template:" wp-content/themes/generatepress-child/style.css
Step 3: Check Files Exist
verify-theme-files.sh
cd /var/www/html
test -f wp-content/themes/generatepress-child/functions.php && echo "functions.php OK"
test -d wp-content/themes/generatepress && echo "parent theme OK"
Step 4: Check Logs
check-logs.sh
ls -lah /usr/local/lsws/logs 2>/dev/null | head -n 20 || true
Step 5: Verify Child Asset Files Exist
verify-child-assets.sh
cd /var/www/html
ls -lah wp-content/themes/generatepress-child/assets 2>/dev/null | head -n 40 || true
Prevention Checklist
| Practice | Why |
|---|---|
| Keep changes small per deploy | Easier rollback |
| Use Git and tags | Audit trail |
| Keep a rollback command | Downtime control |
| Test logged-out | Cache differences |
Issue Matrix
| Symptom | Cause | Fix |
|---|---|---|
| White screen | PHP fatal error | Check logs and roll back |
| Theme "broken" | Bad Template header | Fix Template: generatepress |
| CSS not updating | Cache | Purge LSCache and confirm versioning |
| Hook not firing | Wrong hook/template | Confirm with grep |
| Site differs logged-in | Caching variance | Compare logged-out and purge caches |
| Theme updates overwrite changes | Edited parent theme | Move changes into child theme and re-deploy |
Recovery Steps
- Introduce a controlled change (add a banner hook).
- Confirm it renders.
- Break it intentionally on staging (syntax error), then recover using rollback.
- Document the recovery steps.
- Create a checklist you will follow before every deploy.
Quick Reference
troubleshooting-cheatsheet.sh
cd /var/www/html
wp option get stylesheet
wp theme activate generatepress
What's Next
- Next module: Custom CSS, PHP & Hooks
- Next lesson: Custom CSS Integration