Troubleshooting

Common Issues

1. Permalinks Return 404

Symptom: Pages return 404 errors after deployment or database import.

Fix (immediate):

1. WordPress Admin → Settings → Permalinks → Click "Save Changes"

Fix (WP-CLI):

wp rewrite flush
# or
wp clear-rewrites

Automated fix: The dezeen-rewrites plugin runs an hourly cron job (check_rewrite_rule_event) that checks and regenerates rewrite rules if missing.

2. White Screen / Fatal Error

Symptom: Blank white page or PHP fatal error.

Debug steps:

1. Enable debug logging (temporarily):

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

2. Check _project/_web/wp-content/debug.log
3. Common causes:
   • Memory exhaustion → increase WP_MEMORY_LIMIT
   • Plugin conflict → disable plugins one by one
   • PHP version incompatibility

3. Sass/CSS Build Fails

Symptom: npm run dev or npm run production fails with SCSS errors.

Fix:

cd _project/_web
rm -rf node_modules
npm install
npm run dev

If libsass issues persist:

brew install libsass
LIBSASS_EXT="no" npm install

4. Assets Not Loading

Symptom: CSS/JS files return 404 or appear unstyled.

Check:

1. Verify assets are compiled: ls _project/_web/wp-content/themes/2016dezeen/assets/css/style-min.css
2. Check STATIC_ASSETS_DIRECTORY in wp-config.php
3. For local dev, should be: /wp-content/themes/2016dezeen/assets
4. For production: https://static.dezeen.com/d/assets
5. Run npm run dev to rebuild

5. Algolia Search Not Working

Symptom: Search returns no results or errors.

Check:

1. Verify Algolia constants in wp-config.php:

   ALGOLIA_APPLICATION_ID
   ALGOLIA_SEARCH_API_KEY
   ALGOLIA_INDEX_NAME_PREFIX

2. Verify index exists in Algolia dashboard
3. Check that only ONE Algolia PHP plugin is active (php7 OR php8, not both)
4. Re-index if needed (via Algolia admin or WP-CLI)

6. Newsletter Signup Fails

Symptom: Campaign Monitor form returns error.

Check:

1. Verify Campaign Monitor constants:

   CAMPAIGN_MONITOR_API_KEY
   CAMPAIGN_MONITOR_CLIENT_ID
   CAMPAIGN_MONITOR_LIST

2. Test connection: POST to dezeen-campaign-monitor/v1/test-connection (admin only)
3. Check REST API: GET dezeen-campaign-monitor/v1/test

7. Cache Showing Stale Content

Symptom: Published changes not visible on the live site.

Fix order:

1. Check if Cloudflare is serving stale: curl -I https://www.dezeen.com/ | grep cf-cache-status
2. Purge via dezeen-cloudflare-purge-manager plugin
3. Purge Varnish (from server): varnishadm "ban req.url ~ ."
4. Clear WP Rocket cache (admin)
5. See runbooks/cache-purge.md for full procedure

8. Slow Admin / Timeouts

Symptom: WordPress admin is slow, queries timing out.

Check:

1. Enable Query Monitor plugin for profiling
2. Check SAVEQUERIES constant (should be false in production)
3. Check memory: current limit is 1024M
4. Review ACF fields — heavy ACF usage causes slow cold starts
5. Check database indexes: setup/optimisations/db-indexes.txt
6. Run dezeen-performance-optimiser to check autoloaded options

9. WP Rocket Warnings in Error Log

Symptom: RecursiveDirectoryIterator warnings in debug.log.

Fix: The wp-rocket-cache-busting-fix.php mu-plugin should suppress these. If warnings persist, check the mu-plugin is loading (verify mu-plugins/index.php includes it).

10. Images Not Being Optimised

Symptom: New uploads are not being processed by Smush.

Check:

1. Verify smush-archive-guard.php — only blocks images uploaded before 2026-01-15
2. Check Smush Pro plugin is active and configured
3. Verify CDN is serving optimised images from static.dezeen.com

11. Events Guide Not Showing Events

Symptom: Events page shows no events.

Check:

1. Test REST endpoints:
   • GET /wp-json/events-guide/v1/events
   • GET /wp-json/events-guide/v1/filters
2. Check custom tables exist: vetg_events_guide, vetg_events_guide_types, vetg_events_guide_city_guides
3. Verify the dezeen_event post type is registered

12. Docker Environment Issues

Symptom: Docker environment not working correctly.

Fix:

docker-compose down
docker-compose up -d

# Check container status
docker-compose ps

# Check WordPress logs
docker-compose logs wordpress

# Access database
# PHPMyAdmin: http://localhost:8080
# Credentials: dezeenuser / dezeenpass

Debug Tools

Tool	Access	Purpose
Query Monitor	WP Admin bar (when active)	SQL queries, hooks, HTTP requests
WordPress Ray	Ray desktop app	Visual debugging (dev only)
WP Crontrol	Tools → Cron Events	View/manage cron jobs
debug.log	wp-content/debug.log	PHP error log
Varnish logs	varnishlog on server	Cache hit/miss analysis
Cloudflare	Cloudflare dashboard	CDN analytics, WAF logs

Useful WP-CLI Commands

# Check site health
wp doctor check --all

# List active plugins
wp plugin list --status=active

# Check cron events
wp cron event list

# Run due cron events
wp cron event run --due-now

# Flush rewrite rules
wp rewrite flush

# Flush object cache
wp cache flush

# Search-replace URLs (e.g., after DB import)
wp search-replace 'https://www.dezeen.com' 'https://dezeen.test' --dry-run

# Export database
wp db export backup.sql

# Check database tables
wp db tables

Log File Locations

Log	Location	Notes
WordPress debug	_project/_web/wp-content/debug.log	When WP_DEBUG_LOG = true
Apache error	/var/log/apache2/error.log	Server-level errors
Varnish	varnishlog command	Real-time Varnish logs
PHP	PHP error log (varies by config)	ini_get('error_log')