How to Fix Mastodon Image Upload Stuck on ‘Processing’

When you upload an image to Mastodon and the upload indicator hangs on “Processing” indefinitely, the post cannot be published. This problem affects both the web interface and mobile apps, preventing media from appearing in your toots. The root cause is usually a server-side media processing failure, a file format issue, or a browser cache conflict. This article explains why the processing step stalls and provides specific steps to resolve the issue quickly.

Why Mastodon Gets Stuck on “Processing” During Image Upload

Mastodon does not store uploaded images in their original form. When you attach a file, the server runs a media processing pipeline that generates thumbnails, resizes the file, and extracts metadata. This pipeline uses a background job system called Sidekiq. If Sidekiq is overloaded, misconfigured, or the image file contains unsupported data, the job never completes. The web interface shows “Processing” indefinitely because it is waiting for a success signal from the background worker that never arrives.

Common triggers include:

• Images with very high resolution (over 4000 pixels on the longest side) that exceed the server’s processing time limit.
• Files saved with unsupported color profiles, such as CMYK or Adobe RGB.
• Animated PNG or WebP files that the server’s image library cannot decode.
• A full Sidekiq queue caused by many users uploading media simultaneously.
• Outdated or corrupted browser cache storing a stale JavaScript file that handles the upload progress callback.

Steps to Fix the Stuck Image Upload

Method 1: Clear Browser Cache and Refresh the Page

1. Open browser developer tools
   Press Ctrl+Shift+I on Windows or Cmd+Option+I on Mac to open DevTools.
2. Go to the Application or Storage tab
   In Chrome or Edge, click the Application tab. In Firefox, click Storage. In Safari, click the Storage tab.
3. Clear cache for your instance domain
   Expand the Cache section, select Cache Storage, right-click your Mastodon instance domain (e.g., mastodon.social), and choose Delete. Also clear the HTTP cache by clicking Clear site data in the Application panel.
4. Reload the Mastodon page
   Press Ctrl+F5 or Cmd+Shift+R to force a full page reload. Try uploading the image again.

Method 2: Convert the Image to a Compatible Format and Smaller Size

1. Check the image format
   Mastodon supports JPEG, PNG, GIF, and WebP. Avoid TIFF, BMP, HEIC, and SVG.
2. Reduce resolution to under 2000 pixels on the longest side
   Use an image editor such as Paint on Windows, Preview on Mac, or a free online tool like Pixlr. Resize the image to 1920×1080 or smaller.
3. Convert to sRGB color profile
   If you used a professional photo editor, export the image with the sRGB IEC61966-2.1 color profile. Mastodon’s image library may fail on Adobe RGB or ProPhoto RGB profiles.
4. Save as JPEG with quality 85% or as PNG-24
   JPEG files under 10 MB process fastest. PNG files with transparency are supported but should be under 5 MB.
5. Upload the converted file
   Drag the new file into the Mastodon composer. Wait ten seconds. If the processing indicator still shows, move to Method 3.

Method 3: Check Your Instance’s Media Processing Queue

1. Open Sidekiq dashboard
   Add /sidekiq to your instance URL. For example, if your instance is mastodon.social, go to https://mastodon.social/sidekiq. You must be logged in as an admin or moderator.
2. Check the Busy and Enqueued tabs
   Click the Busy tab. Look for jobs named MediaProcessingWorker or ThumbnailGenerationWorker. If there are many busy jobs, the server is overloaded. Click the Enqueued tab and check the default queue. A high number means jobs are waiting.
3. Restart Sidekiq if the queue appears stuck
   If the same job stays in Busy for more than five minutes with no progress, the worker may be deadlocked. Ask your instance admin to restart Sidekiq with the command systemctl restart mastodon-sidekiq on the server.
4. Wait for the queue to drain
   If the queue is simply full, wait fifteen minutes and try uploading again. Large instances may experience delays during peak hours.

Method 4: Disable Browser Extensions That Interfere with Uploads

1. Open your browser’s extension manager
   In Chrome, go to chrome://extensions. In Firefox, go to about:addons. In Edge, go to edge://extensions.
2. Disable content blockers and script managers
   Turn off uBlock Origin, NoScript, Privacy Badger, or similar extensions temporarily. These can block the JavaScript that reports upload progress.
3. Reload Mastodon and upload again
   If the upload succeeds, re-enable extensions one by one to identify the offender. Add an exception for your Mastodon instance in the extension’s settings.

If Mastodon Still Shows “Processing” After the Main Fix

Upload works in a private browsing window but not in the main browser window

This confirms that the cause is a corrupted cache or an extension in the main profile. Clear all site data for your Mastodon instance in the main browser settings. Go to Settings > Privacy and Security > Cookies and other site data > See all site data. Search for your instance domain and click Remove.

Upload fails on mobile app but works on web

The mobile app may use a different media processing endpoint. Force close the app, clear its cache in the system settings, and restart your phone. If the problem persists, uninstall and reinstall the app from the official app store.

Upload fails on all devices and browsers

The issue is server-side. The instance’s media storage may be full, or the Sidekiq process may have crashed. Contact your instance admin and ask them to check the Mastodon logs with journalctl -u mastodon-web -n 50 and to verify free disk space with df -h.

Image uploads work but video uploads get stuck

Video transcoding requires more CPU and memory than image processing. The instance may have a file size limit for videos, typically 40 MB. Convert your video to MP4 with H.264 encoding, a resolution of 720p or lower, and a bitrate under 2 Mbps. If the problem continues, the server may lack FFmpeg or have a misconfigured transcoding timeout.

Mastodon Image Upload vs Video Upload: Processing Differences

Item	Image Upload	Video Upload
Background worker	MediaProcessingWorker	VideoProcessingWorker
Typical processing time	1 to 5 seconds	10 seconds to 2 minutes
Common stuck cause	Unsupported color profile or corrupted cache	Missing FFmpeg or full disk
File size limit	10 MB (default)	40 MB (default)
Resolution limit	2000 px on longest side	1920×1080

After applying the steps above, your Mastodon image uploads should complete within a few seconds. If you manage your own instance, monitor the Sidekiq dashboard regularly to catch queue buildups early. For recurring problems, set up a cron job that restarts Sidekiq every night at low traffic hours to clear stuck workers automatically.