When you try to open a Mastodon instance in a browser and see a Cloudflare-branded 502 Bad Gateway error, the web server cannot complete your request. This error means Cloudflare, the reverse proxy in front of the Mastodon server, received an invalid response from the origin server. The issue is almost always on the server side, not your local network or browser. This article explains the three most common technical causes of this error on Mastodon instances and what administrators can do to fix them.
Key Takeaways: Cloudflare 502 Bad Gateway on Mastodon
- Upstream server timeout: The Mastodon web process (Puma or Unicorn) fails to respond within Cloudflare’s 100-second limit, often due to slow database queries.
- Origin server crash or restart: The Mastodon application server stops running or restarts during a request, causing Cloudflare to receive no valid HTTP response.
- Firewall or rate limiting on origin: The server’s own firewall (iptables, UFW) or a local rate limiter (fail2ban) blocks Cloudflare’s IP ranges, returning a connection reset.
Why Cloudflare Returns a 502 Error on Mastodon Instances
Cloudflare sits between the user’s browser and the Mastodon origin server. When you visit a Mastodon instance, your browser sends a request to Cloudflare’s edge, which then forwards it to the origin server. The origin server must return a valid HTTP response within a specific timeout period, usually 100 seconds. If the origin does not respond, responds with an incomplete header, or returns a TCP RST (reset) packet, Cloudflare generates a 502 Bad Gateway error.
On Mastodon, the origin server is typically a combination of a reverse proxy like Nginx and an application server like Puma or Unicorn. The application server runs the Mastodon Ruby on Rails code. A 502 error almost always points to a problem in this stack. The three most common root causes are:
1. Upstream Timeout: Puma or Unicorn Takes Too Long
Mastodon’s application server must serve a response before Cloudflare’s proxy timeout expires. The default Cloudflare timeout is 100 seconds for HTTP requests on free and pro plans. If a Mastodon page, such as the federated timeline or a media-heavy post, triggers a slow database query, the application server may exceed this limit. Cloudflare then abandons the connection and shows a 502 error.
2. Application Server Crash or Restart
Puma or Unicorn can crash due to memory exhaustion, a bug in a Mastodon update, or a database connection pool depletion. When the process stops, Nginx cannot forward the request to a healthy worker. The connection to Cloudflare either hangs or returns an empty response. Cloudflare interprets this as a bad gateway.
3. Origin Firewall Blocking Cloudflare IPs
Some Mastodon servers run firewalls that block traffic from unknown IP addresses. If the administrator configures a firewall rule that accidentally blocks Cloudflare’s proxy IP ranges, the origin server refuses the connection. Cloudflare receives a TCP reset or no response at all and returns a 502 error.
How to Diagnose and Fix Each Cause on the Server
These fixes require command-line access to the Mastodon server. You need root or sudo privileges.
- Check the Nginx error log for upstream timeouts
Runsudo tail -f /var/log/nginx/error.logwhile reproducing the 502 error. Look for lines containing “upstream timed out” or “504 Gateway Time-out”. These confirm that the application server is too slow. - Increase the Puma worker timeout in Mastodon’s configuration
Edit the file.env.productionand add or change the lineSTREAMING_API_BASE_URL=http://localhost:4000andWEB_CONCURRENCY=2to reduce load. For the timeout, addPUMA_WORKER_TIMEOUT=120. Then restart Mastodon withsystemctl restart mastodon-web. - Verify that Puma or Unicorn is running
Runsystemctl status mastodon-weborps aux | grep puma. If the process is missing, restart it withsystemctl restart mastodon-web. Check the journal for crash reasons:journalctl -u mastodon-web -n 50. - Allow Cloudflare IP ranges in the firewall
Download the current list of Cloudflare IPv4 ranges withcurl -s https://www.cloudflare.com/ips-v4. Add each range to your firewall, for example with UFW:sudo ufw allow from 173.245.48.0/20 to any port 443 proto tcp. Then reload:sudo ufw reload. - Test the origin directly bypassing Cloudflare
Temporarily set a local hosts file entry pointing your domain to the server’s IP. Access the site directly. If the page loads without a 502, the problem is Cloudflare configuration or IP blocking. If the error persists, the problem is on the origin server.
Related Failure Patterns and Their Causes
502 Error Only on Certain Pages Like the Federated Timeline
If the error appears only when browsing the federated timeline or a specific user’s media-heavy page, the application server is likely timing out on a slow database query. The federated timeline queries the statuses table for public posts from remote instances. A large result set without proper indexing can take longer than 100 seconds. The fix is to add database indexes or increase the puma_worker_timeout.
502 Error After a Mastodon Update
After running mastodon update or git pull, the application server may fail to start because of missing gems or a database migration that did not complete. Check the migration status with RAILS_ENV=production bundle exec rails db:migrate:status. Run any pending migrations with RAILS_ENV=production bundle exec rails db:migrate and then restart the web process.
502 Error During High Traffic Spikes
When a Mastodon instance becomes popular, the default number of Puma workers may be too low. Each worker handles one request at a time. If all workers are busy, new requests queue up and eventually time out. Increase the WEB_CONCURRENCY value in .env.production to match the number of CPU cores. Restart Mastodon after changing this value.
Cloudflare 502 vs Other 5xx Errors on Mastodon
| Item | Cloudflare 502 Bad Gateway | 503 Service Unavailable (Cloudflare) | 504 Gateway Timeout (Cloudflare) |
|---|---|---|---|
| Description | Cloudflare received an invalid or empty response from the origin | Origin server is overloaded or temporarily down | Origin did not respond within Cloudflare’s timeout window |
| Typical cause on Mastodon | Puma crash, firewall block, or incomplete HTTP response | Server under DDoS or out of memory | Slow database query or too few Puma workers |
| Cloudflare retry behavior | No automatic retry; user must refresh | May retry after a few seconds if configured | No automatic retry; user sees an error page |
| Fix priority | Check application server logs and firewall rules first | Scale server resources or enable Cloudflare DDoS protection | Increase Puma timeout or optimize database queries |
Understanding which specific 5xx error appears helps narrow down the root cause. A 502 error almost always requires checking the application server status and firewall configuration, while a 504 points to performance tuning.
After diagnosing the cause, you can take the appropriate action: increase timeouts, restart crashed processes, or allow Cloudflare IPs through the firewall. If the error persists after all fixes, run curl -I https://yourinstance.social from the server itself. A successful response with a 200 status code confirms the origin is healthy. From there, re-examine Cloudflare’s proxy settings and ensure DNS records are set to Proxied (orange cloud).