You try to upload a photo to Mastodon, but the server rejects it with a generic failure message. The most common reasons are that the file exceeds the instance’s size limit or uses an unsupported image format. Each Mastodon server independently sets these restrictions, so limits vary widely between instances. This article explains the exact file size caps and accepted formats for Mastodon, shows you how to check your instance’s limits, and provides step-by-step methods to resize or convert images so your uploads succeed.
Key Takeaways: Mastodon Image Upload Limits and Fixes
- Preferences > Appearance > Custom CSS: Not related to uploads, but the server admin panel under Admin > Server Settings > Uploads shows the exact size cap for your instance.
- Maximum file size: Default is 8 MB for images on most instances, but many administrators raise or lower this value.
- Accepted image formats: JPEG, PNG, GIF, and WebP are universally supported; AVIF and BMP may fail on older instances.
Why Mastodon Rejects an Image Upload: File Size and Format Restrictions
Mastodon instances use two separate server-side checks before accepting an uploaded image. The first check compares the file’s byte size against the instance’s configured max_file_size value. The second check verifies the file extension and MIME type against a whitelist of allowed formats. If either check fails, the server returns an HTTP 422 Unprocessable Entity error or a generic “Upload failed” message in the web interface.
The default max_file_size in Mastodon’s source code is 8 megabytes for images. Instance administrators can change this value in the environment file or through the admin dashboard. Many popular instances, such as mastodon.social, keep the 8 MB limit. Smaller or specialized instances may set a lower limit of 2 MB or 4 MB to save storage costs. Some instances allow up to 16 MB or even 32 MB for images.
The format whitelist typically includes JPEG, PNG, GIF, and WebP. Mastodon also accepts SVG in some instances, but many block it due to security concerns. AVIF and BMP are not in the default whitelist. If you upload an AVIF file, the server will reject it even if the file size is under the limit. The server also checks the actual content of the file, not just the extension. Renaming a .png file to .jpg will not bypass the check.
How to Check Your Instance’s Upload Limits
You can find the exact limits for your instance without asking the admin. Open any Mastodon client and try to upload an image that is clearly too large, such as a 20 MB JPEG file. The error message often states the maximum allowed size. If you have access to the admin panel, navigate to Administration > Server Settings > Uploads. The Maximum image file size field shows the current limit in megabytes. The Allowed image types list shows which extensions the server accepts.
You can also check the instance’s /api/v1/instance endpoint. Open a browser and go to https://yourinstance.social/api/v1/instance. Look for the max_media_attachments key inside the configuration object. The value is the size limit in bytes. Divide by 1,048,576 to get the size in megabytes. The endpoint does not list allowed formats, so you must rely on the admin panel or a test upload for format verification.
Steps to Fix a Failed Image Upload on Mastodon
- Check the file size before uploading
Right-click the image file on your computer and select Properties on Windows or Get Info on macOS. The file size appears in the dialog. If the size exceeds 8 MB, you must reduce it. - Resize the image to reduce file size
Use a free online tool such as TinyPNG or Squoosh. Alternatively, open the image in an image editor. Reduce the longest dimension to 1920 pixels or less. Save the file as JPEG with a quality setting of 80 percent. This usually brings the file size below 2 MB. - Convert the image to a supported format
If the file is AVIF, BMP, or TIFF, convert it to JPEG or PNG. Use the same online tool or the built-in Paint app on Windows. Open the file in Paint, select File > Save as, and choose JPEG picture. On macOS, open the file in Preview, select File > Export, and choose JPEG. - Rename the file to remove special characters
Mastodon’s upload handler may reject files with unusual characters in the filename, such as brackets, emoji, or spaces. Rename the file using only letters, numbers, hyphens, and underscores. For example, renamephoto (1).jpgtophoto-1.jpg. - Upload the image again
Drag the modified file into the Mastodon compose box. Wait for the upload progress indicator to finish. If the upload still fails, the file size is still too large or the format is still unsupported. Repeat steps 2 and 3 with more aggressive compression.
Common Upload Failures and How to Solve Them
“Upload failed” error with a small image file
If the file is under 1 MB but still fails, the format is likely the problem. Verify the file extension. Some image editors save files with a .jfif extension instead of .jpg. Rename the extension to .jpg or re-save the file as JPEG using the editor. If the format is correct, check the filename for special characters as described in step 4 above.
Animated GIF upload fails despite being under the size limit
Mastodon imposes a separate frame count limit on animated GIFs. The default maximum is 100 frames. If your GIF has more than 100 frames, the server will reject it even if the file size is under 8 MB. Use a GIF editor to reduce the frame count to 100 or fewer. You can also convert the GIF to a video file and upload it as a video attachment, which has a separate size limit.
Upload works on one instance but fails on another
Different instances have different limits. The instance where the upload fails likely has a lower max_file_size value. Reduce the image file size further until it meets the stricter limit. If you frequently upload large images, consider moving to an instance with higher limits or ask your admin to increase the limit.
Mastodon Image Limits vs Other Platforms
| Item | Mastodon (default) | Twitter / X |
|---|---|---|
| Max image file size | 8 MB | 5 MB |
| Supported formats | JPEG, PNG, GIF, WebP | JPEG, PNG, GIF, WebP |
| Max GIF frames | 100 | Not limited by frames |
| Image dimensions limit | No hard limit (server may resize) | 4096 x 4096 pixels |
Mastodon’s default image size limit is higher than Twitter’s 5 MB limit, but the format support is nearly identical. The main difference is the GIF frame restriction, which does not exist on Twitter. Mastodon instances can also be configured to strip EXIF metadata automatically, which reduces file size without user action.
Conclusion
You can now identify why a Mastodon image upload failed by checking the file size against your instance’s limit and verifying the format. Resize the image to under 8 MB using a tool such as Squoosh or an image editor, and convert unsupported formats like AVIF to JPEG or PNG. If you encounter repeated failures, check the admin panel under Administration > Server Settings > Uploads for the exact limits. For animated GIFs, keep the frame count at 100 or fewer to avoid silent rejection. These steps will resolve nearly all image upload errors on any Mastodon instance.