Mastodon Export ‘Download Pending’ Forever: Fix Steps

You request an export of your Mastodon data, but the download status stays on “Download pending” for hours or even days. This problem usually occurs when the background job queue on your Mastodon server is overloaded or stuck on a failed task. The server never generates the export file, leaving you with no way to back up your posts, lists, and follows. This article explains why exports get stuck and provides step-by-step fixes for both instance users and server administrators.

Why Mastodon Exports Get Stuck on “Download Pending”

Mastodon does not create export files instantly. When you click a download button on the Preferences > Import and export > Data export page, the system enqueues a background job handled by Sidekiq, the job processor. Sidekiq picks up the job, runs the ExportWorker class, and writes the archive to a temporary location. The web interface then shows a download link instead of the “Download pending” message.

The job can stay pending for three main reasons:

Sidekiq Queue Is Backed Up

If your Mastodon instance processes a high volume of tasks — federating posts, sending notifications, or generating thumbnails — the export job sits behind other tasks. A queue with thousands of waiting jobs can delay an export by hours.

A Failed Job Blocks the Queue

Sometimes a previous export job fails because of a missing file, a database timeout, or an out-of-memory error. Sidekiq retries the failed job multiple times, but if the root cause persists, the job stays in the retry set. New export jobs for the same user may be blocked until the old job is resolved.

The Export Worker Crashes Without a Retry

On smaller instances with limited RAM, the ExportWorker can consume too much memory and be killed by the operating system. Sidekiq does not always re-enqueue the job after an OOM kill, leaving the export status as “Download pending” permanently.

Steps to Unstick a Pending Mastodon Export

The fix method depends on whether you are a regular user or a server administrator. Follow the section that applies to your role.

For Regular Users: Cancel and Re-request the Export

1. Open Preferences > Import and export > Data export
   Navigate to your Mastodon settings. The data export page lists all export types: posts, media, lists, bookmarks, follows, blocks, mutes, and domain blocks.
2. Click the “Request” button for the stuck export type again
   If the button is grayed out or shows “Download pending,” wait 30 seconds and refresh the page. If the status does not change, proceed to the next step.
3. Log out and log back in
   Logging out clears your session cache. After logging in again, go back to the data export page. The stuck job may have been cleared by the server in the meantime. If the button is now clickable, request the export again.
4. Contact your instance admin
   If the export is still pending after logging out, the issue is on the server side. Send a direct message to your instance admin with the exact export type that is stuck. Include the time you first requested it.

For Server Administrators: Clear the Stuck Job via Sidekiq

1. Access the Sidekiq dashboard
   Open https://your-instance.example.com/sidekiq in a browser. You must have admin privileges and be logged in to your Mastodon account. If you see a 404 error, your instance may have Sidekiq web disabled — use the Rails console method instead.
2. Navigate to the Retries tab
   Click the “Retries” link at the top of the Sidekiq dashboard. Look for jobs with the class ExportWorker. The job payload contains the user ID of the affected account.
3. Delete or retry the ExportWorker job
   Click the “Delete” button to remove the stuck job entirely. Alternatively, click “Retry” to attempt the export again immediately. If the job fails again within seconds, delete it and ask the user to request a fresh export.
4. Check the Busy tab for a running ExportWorker
   A job stuck in the “Busy” state means Sidekiq is trying to process it but cannot finish. Restart the Sidekiq process on your server: run systemctl restart mastodon-sidekiq on a systemd-based setup. After the restart, the job will be retried or moved to the Dead tab.

For Server Administrators: Purge All Pending Exports via Rails Console

1. Open a Rails console session
   SSH into your Mastodon server and run cd /home/mastodon/live && RAILS_ENV=production bin/rails console. Replace the path with your Mastodon installation directory if different.
2. Delete all pending export jobs
   Type the following command and press Enter:
   Sidekiq::Queue.new("default").each { |job| job.delete if job.display_class == "ExportWorker" }
   This removes every queued export job from the default queue.
3. Clear the retry set for export jobs
   Run:
   Sidekiq::RetrySet.new.each { |job| job.delete if job.display_class == "ExportWorker" }
   This removes any failed export jobs that Sidekiq was planning to retry.
4. Ask the user to request the export again
   After purging the jobs, the user will see a fresh “Request” button on their data export page. Instruct them to click it and wait up to five minutes for the file to appear.

If the Export Still Shows “Download Pending” After the Main Fix

Export File Exceeds Server Storage Limits

Mastodon stores export files in a temporary directory, typically /home/mastodon/live/public/system/export. If the disk is full, Sidekiq cannot write the archive. Run df -h on your server to check disk usage. Free up space by removing old exports or increasing storage.

Media Export Times Out on Large Accounts

The media export archive contains all files you have uploaded. An account with thousands of images can cause the worker to exceed Sidekiq’s 25-minute default timeout. Increase the timeout in your Sidekiq configuration or advise the user to request a posts-only export instead.

Browser Cache Shows a Stale Status

Even after the export completes, your browser may display the old “Download pending” message. Clear the browser cache for your Mastodon instance or open the export page in a private browser window. If the download link appears there, the export is ready.

Custom Theme or Extension Interferes with the UI

Browser extensions that modify Mastodon’s web interface can hide the download link. Disable all extensions temporarily and reload the data export page. If the button appears, re-enable extensions one by one to find the culprit.

Item	Queue Check via Sidekiq	Queue Check via Rails Console
Skill level needed	Intermediate (admin login required)	Advanced (SSH and command line)
Time to execute	2-5 minutes	5-10 minutes
Removes retried jobs	Yes, manually per job	Yes, bulk delete by class
Requires server restart	Only if job is stuck in Busy state	No
Risk of data loss	None	None (deletes only queued job, not the export data)

You now know why Mastodon exports get stuck and how to fix them on both the user and admin side. For regular users, the quickest fix is to log out and log back in, then request the export again. If that fails, ask your admin to clear the Sidekiq queue. Server administrators should first check the Sidekiq dashboard for stuck ExportWorker jobs, then use the Rails console to purge all pending exports if the queue is deeply blocked. After the fix, verify that the export completes within five minutes. For ongoing prevention, monitor your Sidekiq queue depth daily and restart the service if the queue exceeds 500 jobs.