WP Hummingbird - Troubleshooting Guide

This document outlines best practices for using WP Hummingbird’s Asset Optimization features, with a focus on manual optimization and troubleshooting strategies. WP Hummingbird is a powerful tool, but incorrect configurations—especially under the Automatic mode—can cause significant front-end issues. This guide is designed to help you diagnose and resolve those issues efficiently.


Why Not Use Automatic Optimization?

While Hummingbird offers an Automatic Asset Optimization option, it is not recommended for production sites. The automatic feature tends to:
  • Combine critical JavaScript and CSS files indiscriminately
  • Minify assets in the wrong order or context
  • Break site functionality (navigation, sliders, layout, forms, etc.)
Instead, always use Manual Mode for greater control and predictability.


Manual Asset Optimization: Interface Overview

When using Manual Mode, Hummingbird provides control over individual CSS and JS assets. You will see each file listed with the following options:
  • Minify: Compresses the file by removing whitespace and comments. Recommended for nearly all files.
  • Combine: Merges the file with others into a single file to reduce HTTP requests. Use cautiously—improper combinations can break the site.
  • Defer/Inline/Move to Footer: Advanced options that affect the load order. Only modify if you understand the asset’s function and placement.
  • Ignore: Excludes the file from optimization. Use this if minification or combination causes breakage.


Best Practices for Manual Optimization

1. After Adding or Removing Plugins: Run “Re-Check Files”

Whenever plugins or themes are added, updated, or removed, use the Re-Check Files button. This ensures:
  • New scripts/styles are detected
  • Old or orphaned assets are removed from the optimization queue
This step helps maintain a clean and accurate asset list.


2. Reset Settings After Switching from Automatic to Manual

If the site was previously using Automatic Optimization, switching to Manual will retain the (possibly broken) settings. Perform a clean reset by:
    Switching to Manual Mode
    Setting all CSS and JS files to:
  • Minify: ON
  • Combine: OFF
This provides a safe baseline for beginning an iterative optimization process.


3. Iterative Optimization Strategy (Recommended)

To avoid breaking the site and to make issues easier to trace, optimize assets incrementally:
    Start with all files minified, none combined
    Pick one plugin or module (e.g., a slider, form, or contact plugin)
    Enable Combine for only that plugin’s CSS and JS files
    Monitor the site over the next 5–7 days:
  • Test in multiple browsers and devices
  • Check for layout issues or console errors
    If everything works fine, repeat with another plugin
    Stop when additional combinations start causing problems
This controlled process allows you to identify which assets cause conflicts and rollback easily if needed.


4. Diagnosing Display Errors Using ?avoid-minify=true

If a layout or script issue is observed, append this query string to the URL:
?avoid-minify=true
This temporarily bypasses Hummingbird’s minification and combination. If the issue disappears with this parameter, it's likely related to asset optimization.
Next Steps:
    Open the affected page with ?avoid-minify=true
    Open the browser’s Element Inspector (Right-click > Inspect Element or F12)
    Identify key scripts and styles related to the broken elements
    Return to the Hummingbird Asset Optimization panel and:
  • Set those files to "Ignore"
  • Or disable Combine for them if that was enabled
This method helps you isolate the problem file(s) and fine-tune optimization settings.


Features to Use Cautiously (or Avoid)

1. WPMU CDN

  • Rarely used on our sites due to frequent URL mismatches and file load failures
  • Causes more problems than it solves in most WordPress environments

2. Delay JavaScript Execution

  • While useful for improving Lighthouse/PageSpeed scores, it often breaks interactive elements like:
  • Menus
  • Sliders
  • Forms
  • Only enable after extensive testing, and never in combination with heavy JS-based plugins

3. Critical CSS

  • Auto-generated critical CSS can conflict with layout styling
  • Causes flashes of unstyled content (FOUC) or broken layouts
  • Use only with a full visual regression testing strategy


Additional Troubleshooting Tips

  • Use Browser Console Logs: JS errors in the console often point to the exact script causing problems
  • Clear All Caches: After any changes, clear:
  • Hummingbird cache
  • Browser cache
  • Page cache (if using a plugin like WP Rocket or W3 Total Cache)
  • Use Incognito Mode: Always test in incognito/private browsing to avoid cached assets
  • Check Asset Load Order: JavaScript files often depend on load order. Do not defer or move to the footer without confirming compatibility
  • Check for Inline Scripts: If a script is inline and depends on a combined/minified external file, they must load in the right order
  • Monitor with PageSpeed Tools: Use  PageSpeed Insights  or  GTmetrix  to confirm asset optimizations are taking effect


Summary

Task
Recommendation
Optimization Mode
Always use Manual
Initial Settings
Minify all, Combine none
After Plugin Changes
Run “Re-Check Files”
Optimization Process
Combine one module at a time, test for 1 week
Troubleshooting Tool
?avoid-minify=true to isolate problems
Advanced Features
Use CDN, Delay JS, and Critical CSS sparingly
Issue Diagnosis
Use browser inspector and console logs

By following this guide, you can optimize performance while maintaining stability and minimizing risk. Each site may behave slightly differently depending on its theme and plugin stack, so a deliberate, iterative approach is always preferred over automation.