Diagnostics & Troubleshooting

#The check command

The accelerate-guru check command is the first tool to reach for when something isn't working:

accelerate-guru check --url https://yourstore.com

It runs a structured battery of checks and outputs a report. Key sections:

#Connection

CONNECTION
  Origin:  http://127.0.0.1:8080 → 200 OK (824ms)
  Proxy:   https://yourstore.com  → 200 OK (4ms) ← CACHE HIT

• If the Origin check fails (connection refused, timeout), Accelerate Guru cannot reach Magento. Check upstream_addr and upstream_port.
• If the Proxy response shows CACHE MISS on every run, the cache is not working. Check DragonflyDB.

#Cache status

CACHE
  DragonflyDB: connected ✓ (127.0.0.1:6379, 234 entries, 4.8 MB)
  Cache hit rate (last 5 min): 94.3%
  Excluded paths applied: /customer/, /checkout/, ...

If DragonflyDB shows not connected, ensure it's running:

sudo systemctl status dragonflydb
redis-cli ping    # → PONG

#Headers

HEADERS
  x-cache:          HIT
  content-encoding: zstd ✓
  x-content-type-options: nosniff ✓
  strict-transport-security: present ✓

#Log files

#Main application log

Linux (systemd):

journalctl -u accelerate-guru -f          # follow live
journalctl -u accelerate-guru --since "1 hour ago"
journalctl -u accelerate-guru -p err       # errors only

Log file (if configured):

tail -f /var/log/accelerate-guru/access.log

#WAF log

tail -f /var/log/accelerate-guru/waf.log

WAF log format:

2026-05-08T14:00:01Z BLOCK ip=203.0.113.42 path=/wp-login.php reason=wordpress_probe ua="Go-http-client/1.1"
2026-05-08T14:00:02Z BLOCK ip=203.0.113.42 path=/admin reason=rate_limit count=32/60s
2026-05-08T14:00:05Z ALLOW ip=8.8.8.8     path=/catalog/product/view/id/1 reason=googlebot_verified

#RUST_LOG — log verbosity

Accelerate Guru uses the RUST_LOG environment variable to control log verbosity. Set it before starting the service.

For systemd, set it in the service override:

sudo systemctl edit accelerate-guru

Add:

[Service]
Environment=RUST_LOG=debug

Then restart:

sudo systemctl restart accelerate-guru

For a one-off debug session:

RUST_LOG=debug accelerate-guru --from-dir /etc/accelerate-guru

Module-level filtering (advanced):

# Only debug logs from the cache module; info everywhere else
RUST_LOG=info,accelerate_guru::cache=debug

# Only trace logs from the WAF
RUST_LOG=warn,accelerate_guru::waf=trace

#The /stats-ag dashboard

Open https://yourstore.com/stats-ag from an IP listed in stats.allowed_ips (default: 127.0.0.1 — use an SSH tunnel or add your IP to the config).

#Overview panel

#Cache panel

#Security panel

#Images panel

#Common errors and fixes

#Error: Address already in use (os error 98) — port 80 or 443 is taken

Something else (Nginx, Apache, or another instance of Accelerate Guru) is listening on port 80/443.

# Find what's using port 80
sudo ss -tlnp | grep :80
sudo lsof -i :80

# Stop the conflicting service
sudo systemctl stop nginx
# or
sudo systemctl stop apache2

Then restart Accelerate Guru:

sudo systemctl restart accelerate-guru

#Cache disabled — cannot reach DragonflyDB at 127.0.0.1:6379

DragonflyDB is not running or is bound to a different address.

sudo systemctl start dragonflydb
redis-cli ping   # → PONG

If DragonflyDB is on a different port or host, update magento_ultra.ini:

[cache]
redis_host = 127.0.0.1
redis_port = 6380   ; if you're using a non-default port

#TLS handshake error: self-signed certificate in certificate chain

When upstream_tls = true and the upstream Magento server has a self-signed certificate, Accelerate Guru refuses it by default (correct security behaviour).

Option 1: set upstream_tls = false and switch Magento to plain HTTP on the loopback interface (recommended — TLS between two local processes is overhead, not security).

Option 2: add the upstream's CA certificate to the system trust store.

#license key invalid or expired

Check the key value in [license]:

• No extra whitespace or newlines.
• Not the dev key on a non-development hostname.
• The key is active in your account dashboard.

#Pages are being served stale after a Magento update

1. Clear the cache from the dashboard: Settings → Cache → Clear all.
2. Or via CLI: redis-cli -n 0 FLUSHDB

#A specific page is never cached

Check:

1. The URL path is not in cache_exclude_paths.
2. The response from Magento does not include Cache-Control: no-store or Set-Cookie with a session value.
3. The request method is GET (not POST).
4. Run with RUST_LOG=debug and look for log lines containing cache_miss reason=....

#The proxy rewrites HTML but breaks a JavaScript component

Some JavaScript components use hardcoded URL patterns that don't match the expected format after domain masking or link rewriting.

1. Check browser console for JavaScript errors.
2. Disable individual HTML transformations in [optimization_html] to isolate the issue.
3. If domain masking is the cause, check the rewrite_inline_js = false option to disable inline JS rewriting.

#Getting support

If you've exhausted the troubleshooting steps above, collect the following before contacting support:

# Attach this output to your support request
accelerate-guru check --url https://yourstore.com --verbose > check-output.txt
RUST_LOG=debug accelerate-guru --from-dir /etc/accelerate-guru 2>&1 | head -200 > debug-log.txt
accelerate-guru --version