Introduction

The RabbitMQ management plugin provides a web UI and HTTP API for monitoring and administering the broker. When deployed behind a reverse proxy (Nginx, HAProxy, or cloud load balancer), misconfiguration can cause the UI to fail to load, WebSocket connections to drop, or API endpoints to return errors, blocking administrative access to the broker.

Symptoms

  • Management UI loads but shows blank dashboard or 404 errors for API calls
  • WebSocket connection for real-time queue metrics fails with connection refused
  • Static assets (CSS, JavaScript) return 404 through the reverse proxy
  • API endpoints return 502 Bad Gateway or 504 Gateway Timeout
  • Error message: WebSocket connection to 'wss://proxy/rabbitmq/ws' failed

Common Causes

  • Reverse proxy not forwarding WebSocket upgrade headers for the management UI real-time channel
  • Incorrect path rewriting stripping the /rabbitmq/ prefix from API requests
  • Proxy timeout too short for long-polling management API endpoints
  • Missing or incorrect Host header causing RabbitMQ to generate wrong URLs
  • SSL termination at the proxy without proper X-Forwarded-Proto header

Step-by-Step Fix

  1. 1.Test direct access to the management plugin: Bypass the proxy to confirm the plugin is working.
  2. 2.```bash
  3. 3.curl -s -u guest:guest http://rabbitmq:15672/api/overview | jq '.cluster_name'
  4. 4.`
  5. 5.Configure reverse proxy to support WebSocket connections: Add WebSocket upgrade headers.
  6. 6.```nginx
  7. 7.# Nginx configuration
  8. 8.location /rabbitmq/ws {
  9. 9.proxy_pass http://rabbitmq:15672/ws;
  10. 10.proxy_http_version 1.1;
  11. 11.proxy_set_header Upgrade $http_upgrade;
  12. 12.proxy_set_header Connection "upgrade";
  13. 13.proxy_set_header Host $host;
  14. 14.}
  15. 15.`
  16. 16.Fix path rewriting for API requests: Ensure the path prefix is preserved.
  17. 17.```nginx
  18. 18.location /rabbitmq/ {
  19. 19.proxy_pass http://rabbitmq:15672/;
  20. 20.proxy_set_header Host $host;
  21. 21.proxy_set_header X-Real-IP $remote_addr;
  22. 22.proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  23. 23.proxy_set_header X-Forwarded-Proto $scheme;
  24. 24.}
  25. 25.`
  26. 26.Increase proxy timeouts for long-polling endpoints: Prevent 504 timeouts.
  27. 27.```nginx
  28. 28.proxy_read_timeout 120s;
  29. 29.proxy_connect_timeout 60s;
  30. 30.`
  31. 31.Verify the management UI works through the proxy: Test both UI and API.
  32. 32.```bash
  33. 33.curl -s -u guest:guest https://proxy.example.com/rabbitmq/api/overview | jq '.cluster_name'
  34. 34.`

Prevention

  • Use a dedicated subdomain for the management UI (e.g., rabbitmq-mgmt.example.com) to avoid path prefix issues
  • Include WebSocket configuration in the standard reverse proxy template for RabbitMQ
  • Set management.listener.ssl = true on the RabbitMQ side when terminating SSL at the proxy
  • Document the reverse proxy configuration as part of the RabbitMQ deployment runbook
  • Test management UI access through the proxy after every proxy configuration change
  • Consider using RabbitMQ's built-in TLS support instead of SSL termination at the proxy