Troubleshooting

Common issues and solutions

API Issues

API Returns 404

Symptoms: API endpoints return "Not Found"

Solutions:

  • Make sure the post is published (not draft)
  • Check the slug is correct (case-sensitive)
  • Verify permalinks: Settings → Permalinks → Post name
  • Flush rewrite rules by saving permalink settings

Empty JSON Response

Symptoms: API returns {}

Solutions:

  • Check if content was compiled: Dashboard → Cache Statistics
  • Manually trigger compilation: Dashboard → Recompile All Content
  • Check queue status: Dashboard → Queue Status

CORS Errors

Symptoms: Browser shows CORS policy errors

Solutions:

  • CORS headers are automatically added by the plugin
  • If still having issues, add to wp-config.php:
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET');

Cache & Compilation Issues

Cache Not Populating

Symptoms: Posts not appearing in cache

Solutions:

  • Check queue status in Dashboard
  • Enable debug logging in wp-config.php:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
  • Check wp-content/debug.log for errors
  • Verify Action Scheduler is working (if installed)

Slow Compilation

Symptoms: Posts take long to compile

This is normal for:

  • Large posts with many images
  • Posts with many ACF fields (Pro)
  • Posts with complex content

Solutions:

  • Compilation runs in background - doesn't slow admin
  • Increase PHP memory limit in wp-config.php:
define('WP_MEMORY_LIMIT', '256M');

Old Content Showing

Symptoms: API returns outdated content

Solutions:

  • Wait a few seconds for background compilation to complete
  • Manually recompile: Dashboard → Recompile All Content
  • Check if WP-Cron is running properly

Authentication Issues

API Key Not Working

Symptoms: Preview mode returns 403 Forbidden

Solutions:

  • Verify key is in correct format: hb_xxxxx...
  • Check header name: X-Headless-Bridge-Key
  • Regenerate key if lost (keys shown only once)

Rate Limiting

Symptoms: 429 Too Many Requests

Solutions:

  • Wait for rate limit reset (check X-RateLimit-Reset header)
  • Adjust limits in plugin settings
  • Use authenticated requests for higher limits

Pro Features Issues

License Activation Fails

Solutions:

  • Check internet connection from WordPress server
  • Verify license key format
  • Contact support if key is valid but won't activate

ACF Fields Not Showing

Symptoms: ACF data missing from API response

Solutions:

  • Verify Pro license is active: Dashboard → License
  • Check ACF plugin is installed and activated
  • Recompile content after activating Pro

Performance Issues

Slow API Response

Expected: <100ms, Should be: <50ms

Solutions:

  • Check if using shared hosting (upgrade recommended)
  • Verify database is optimized
  • Enable compression for large payloads: Settings → Compression
  • Check server location vs. client location

High Memory Usage

Solutions:

  • Normal for compilation of large sites
  • Compilation runs in background, not during requests
  • Increase PHP memory limit if needed

Debug Commands

View Cache Statistics

wp eval-file wp-content/plugins/headless-bridge/test-helper.php stats

Test API Endpoints

wp eval-file wp-content/plugins/headless-bridge/test-helper.php test

Clear and Recompile

wp eval-file wp-content/plugins/headless-bridge/test-helper.php cleanup
wp eval-file wp-content/plugins/headless-bridge/test-helper.php create 5

Still Having Issues?