Troubleshooting Guide

Solutions to common HTTP compression problems and issues

Common Issues and Solutions

Compression Not Working

  1. Check Accept-Encoding header: Ensure client sends proper header
  2. Verify module installation: Confirm compression modules are loaded
  3. Check MIME types: Ensure content types are configured for compression
  4. Test file size threshold: Files may be too small to compress
  5. Review proxy settings: Some proxies strip compression headers

Diagnostic Commands

Quick Diagnostics

# Check if server responds with compression
curl -H "Accept-Encoding: gzip" -I https://example.com

# Verify specific encoding
curl -H "Accept-Encoding: br" -I https://example.com | grep -i encoding

# Test with verbose output
curl -H "Accept-Encoding: gzip, br" -v https://example.com 2>&1 | grep -E "(Accept-Encoding|Content-Encoding)"

# Check actual compression
curl -H "Accept-Encoding: gzip" https://example.com | gunzip -c | wc -c
curl https://example.com | wc -c

Server-Specific Issues

Nginx Troubleshooting

  • Module not loaded: Check nginx -V for --with-http_gzip_module
  • Configuration syntax: Run nginx -t to test config
  • Conflicting directives: Check for gzip_off in location blocks
  • Buffer size issues: Increase gzip_buffers if needed

Nginx Debug Configuration

# Enable debug logging
error_log /var/log/nginx/error.log debug;

# Test specific location
location /test {
    gzip on;
    gzip_types text/plain application/json;
    gzip_min_length 1;
    
    # Add debug header
    add_header X-Compression-Debug "gzip enabled" always;
}

Apache Troubleshooting

  • Module not enabled: Run a2enmod deflate and restart
  • .htaccess override: Check AllowOverride settings
  • mod_deflate vs mod_gzip: Use mod_deflate (modern Apache)
  • LogLevel debug: Enable detailed logging

Apache Debug Configuration

# Enable compression logging
LogLevel warn deflate:trace8

# Test configuration
<IfModule mod_deflate.c>
    # Force compression for testing
    SetOutputFilter DEFLATE
    
    # Log compression ratio
    DeflateFilterNote Input instream
    DeflateFilterNote Output outstream
    DeflateFilterNote Ratio ratio
    LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
    CustomLog /var/log/apache2/deflate.log deflate
</IfModule>

Browser-Related Issues

Client Problems

  • Browser cache serving old versions
  • Proxy stripping headers
  • Antivirus software interference
  • Corporate firewall modifications
  • Browser extensions blocking

Solutions

  • Clear browser cache and cookies
  • Test in incognito/private mode
  • Disable browser extensions
  • Use different network connection
  • Check with curl or wget

Content-Encoding Errors

ERR_CONTENT_DECODING_FAILED

  1. Corrupted compression: Server sending malformed compressed data
  2. Double compression: Content compressed multiple times
  3. Wrong encoding header: Content-Encoding doesn't match actual encoding
  4. Partial content: Incomplete compressed response

Fix Content Encoding Errors

# Nginx - Prevent double compression
location ~* \.(js|css|html)$ {
    gzip_static on;
    gzip off;  # Disable dynamic compression for pre-compressed files
}

# Apache - Fix encoding headers
<FilesMatch "\\.js\\.gz$">
    Header set Content-Encoding gzip
    Header set Content-Type application/javascript
</FilesMatch>

Performance Issues

High CPU Usage

  • Lower compression level: Reduce from 9 to 6 or lower
  • Pre-compress static files: Compress during build process
  • Limit compression types: Only compress text-based content
  • Use hardware acceleration: Intel QAT or similar
  • Cache compressed content: Avoid recompressing same content

Caching Issues

Fix Cache Problems

# Always include Vary header
location / {
    gzip on;
    gzip_vary on;  # Adds "Vary: Accept-Encoding"
    
    # Explicit vary header
    add_header Vary "Accept-Encoding" always;
}

# Clear cache after compression changes
# Nginx
proxy_cache_bypass $http_pragma;
proxy_cache_revalidate on;

# Apache
Header append Cache-Control "no-transform"

CDN and Proxy Issues

CDN Compression Problems

  1. Origin not compressing: Enable compression at origin server
  2. CDN overriding: Check CDN compression settings
  3. Missing Vary header: Causes incorrect caching
  4. Compression disabled: Some CDNs disable for certain file types

Debugging Tools

Advanced Debugging

# Trace HTTP headers
tcpdump -A -s 0 'tcp port 80 and (((ip[2:2] - ((ip[0]&0xf)<<2)) - ((tcp[12]&0xf0)>>2)) != 0)'

# Monitor compression in real-time
watch -n 1 'curl -s -H "Accept-Encoding: gzip" -w "%{size_download} bytes\n" -o /dev/null https://example.com'

# Test with different user agents
curl -H "User-Agent: Mozilla/5.0" -H "Accept-Encoding: gzip" https://example.com

# Check response headers and body
curl -H "Accept-Encoding: gzip" https://example.com -o - | od -c | head

Common Error Messages

Error: Content-Length Mismatch

Cause: Compressed size doesn't match Content-Length

Fix: Remove Content-Length header for compressed responses

Error: Invalid Compressed Data

Cause: Corruption during compression

Fix: Check server resources, lower compression level

Error: Encoding Not Acceptable

Cause: Client doesn't support offered encoding

Fix: Ensure fallback to uncompressed content

Quick Reference

Troubleshooting Checklist

  1. ✓ Verify compression modules are installed and enabled
  2. ✓ Check Accept-Encoding request header
  3. ✓ Confirm Content-Encoding response header
  4. ✓ Test with curl to eliminate browser issues
  5. ✓ Review server error logs
  6. ✓ Check for proxy/CDN interference
  7. ✓ Verify MIME type configuration
  8. ✓ Test file size thresholds
  9. ✓ Ensure Vary: Accept-Encoding is present
  10. ✓ Monitor CPU and memory usage