Mastodon Error 503 ‘Service Unavailable’ During Sign Up: Causes

Mastodon returns a 503 Service Unavailable error when you try to create a new account and the server cannot process the registration request. This error means the instance’s web server is alive but cannot complete the sign-up workflow due to a backend problem. The most common causes include a full database connection pool, a background job queue that is stalled, or a rate-limiting mechanism that blocks new registrations temporarily. This article explains the technical root causes behind the 503 error during sign-up and provides the steps to diagnose and resolve each scenario.

Why Mastodon Returns a 503 Error When You Try to Register

Mastodon uses a multi-process architecture that combines a web server such as Puma, a background job processor called Sidekiq, and a PostgreSQL database. When you submit a registration form, the web server receives the request, validates the input, and then enqueues a background job to send a confirmation email. The web server immediately returns a response to the browser while Sidekiq processes the email job asynchronously. If any component in this chain is overloaded or misconfigured, the web server cannot complete the request and responds with a 503 Service Unavailable status.

The 503 error specifically indicates that the server is temporarily unable to handle the request. Unlike a 500 Internal Server Error, which suggests a code bug, a 503 often points to resource exhaustion or a configuration limit. The three most frequent triggers during sign-up are a stalled Sidekiq queue, a full database connection pool, and rate-limiting rules that block the registration endpoint.

Stalled Sidekiq Queue

Sidekiq processes jobs from a Redis-backed queue. If the Sidekiq process has stopped, crashed, or is running out of memory, the confirmation email job remains in the queue indefinitely. The web server may time out waiting for a job confirmation and return a 503. This scenario is common on smaller instances where administrators run Sidekiq with limited memory or without a process supervisor such as systemd.

Database Connection Pool Exhaustion

Mastodon’s Puma web server maintains a pool of database connections. The default pool size is 5 connections per Puma worker. If many users visit the instance simultaneously, the pool can be exhausted. When a registration request arrives, the web server cannot acquire a database connection to insert the new user record and responds with a 503 error.

Rate Limiting by Rack::Attack

Mastodon includes the Rack::Attack middleware to throttle abusive traffic. By default, it limits sign-up attempts to 5 requests per minute per IP address. When you exceed this limit, Rack::Attack returns a 503 error instead of the standard 429 Too Many Requests status. This behavior is intentional to prevent automated registration bots from overwhelming the instance.

How to Diagnose and Fix the 503 Error During Sign Up

The following steps assume you have administrative access to the Mastodon instance. If you are a regular user trying to sign up, contact the instance administrator and share the steps below so they can run the diagnostic commands.

1. Check if Sidekiq is running
   Log into the server via SSH and run systemctl status mastodon-sidekiq. If the process is inactive or failed, start it with systemctl start mastodon-sidekiq. Enable it to start on boot with systemctl enable mastodon-sidekiq.
2. Inspect the Sidekiq queue for stalled jobs
   Run cd /home/mastodon/live && RAILS_ENV=production bin/tootctl sidekiq stats. Look for the “processed” and “failed” counters. If the queue size is growing or jobs are not being processed, restart Sidekiq with systemctl restart mastodon-sidekiq.
3. Monitor database connection usage
   Run sudo -u mastodon psql -d mastodon_production -c "SELECT count() FROM pg_stat_activity WHERE state = 'active';". If the count is close to the pool size defined in config/database.yml, increase the pool value. For example, change pool: 5 to pool: 10 and restart Puma with systemctl restart mastodon-web.
4. Review Rack::Attack logs
   Check the Mastodon log file at /home/mastodon/live/log/production.log for lines containing “Rack::Attack”. If you see entries like “Rack::Attack: throttled POST /auth” for your IP address, the rate limiter is blocking your registration. Wait one minute and try again, or ask the administrator to increase the limit in config/initializers/rack_attack.rb.
5. Verify Redis connectivity
   Run redis-cli ping. If the response is not “PONG”, restart Redis with systemctl restart redis-server. Sidekiq cannot function without a working Redis connection.

If Mastodon Still Shows a 503 Error After the Main Fix

Registration Is Disabled on the Instance

The instance administrator may have disabled new user registration in the admin panel. Navigate to Preferences > Administration > Server Settings > Registrations and ensure “Open registration” is checked. If it is unchecked, the server will return a 503 error for all sign-up attempts.

Puma Worker Timeout

If the Puma worker timeout is too low, a registration request that triggers a slow database query may be killed before it completes. Check the config/puma.rb file for the worker_timeout setting. The default is 60 seconds. Increase it to 120 seconds if you see frequent timeouts during peak hours.

File System Disk Space Full

Mastodon writes log files and temporary files to disk. If the disk is full, the web server cannot write to the log and returns a 503. Run df -h to check disk usage. If any partition is above 90 percent usage, free up space by rotating logs with logrotate -f /etc/logrotate.d/mastodon or deleting old media files with bin/tootctl media remove.

Mastodon 503 Error vs Other HTTP Status Codes During Sign Up

Item	503 Service Unavailable	429 Too Many Requests	500 Internal Server Error
Description	Server temporarily cannot handle the request due to overload or maintenance	Client has sent too many requests in a given time frame	Server encountered an unexpected condition that prevented it from fulfilling the request
Typical cause	Stalled Sidekiq queue, full database pool, rate limiting	Exceeded Rack::Attack throttle limit	Application code bug, missing gems, or corrupted configuration
Appears during sign up	Yes	Yes, but Mastodon may return 503 instead of 429	Rarely during sign up, more common on other endpoints
Resolution	Restart Sidekiq, increase database pool, wait for rate limit to reset	Wait one minute and retry, or increase throttle limit	Check application logs and fix the underlying code or configuration error

After you resolve the 503 error, you can successfully complete the Mastodon registration process. Start by restarting the Sidekiq service because a stalled job queue is the most frequent cause. If the error persists, increase the PostgreSQL connection pool size in config/database.yml and verify that disk space is not exhausted. For administrators who want to prevent future 503 errors, set up monitoring with a tool like Prometheus to alert on Sidekiq queue depth and database connection usage before they reach critical levels.