Mastodon Alt Text Missing After Media Upload: Fix

You upload an image to Mastodon, write your post, and hit publish. But when you check the post, the alt text you carefully wrote is gone. The media appears without a description, leaving the post inaccessible to screen reader users. This problem occurs because Mastodon’s web interface and some third-party apps handle alt text metadata differently during the upload process. This article explains the root cause of missing alt text and provides a step-by-step fix that works across the web interface and mobile apps.

Why Alt Text Disappears After Uploading Media

Mastodon treats alt text as a property of the media attachment, not of the post itself. When you upload an image, Mastodon creates an attachment record. The alt text field exists inside that record. If you add alt text before the upload finishes, the browser or app may discard the text because the attachment record has not fully formed.

Another common cause is the interface design. In the default web interface, the alt text field appears only after you click the edit button on the uploaded media. Many users type alt text into the main compose box, which Mastodon ignores. The text is not attached to the media, so it vanishes.

Third-party Mastodon apps often reuse the same attachment record across multiple uploads. If you upload a second image while editing the first one’s alt text, the app may overwrite the first attachment’s metadata. The app saves the last set of changes and discards the earlier ones.

How Mastodon Stores Alt Text Internally

Mastodon uses a media attachment API endpoint. Each attachment has a description field. When you submit the post, the client sends a PATCH request to that endpoint with the alt text. If the client sends the request before the description field is populated, the server saves an empty string. The post then shows the media without alt text.

Steps to Recover and Preserve Alt Text on Mastodon

Use these steps to ensure alt text stays attached to your media. The steps work on Mastodon web version 4.x and the official iOS and Android apps.

1. Upload media first, then wait for the thumbnail to appear
   Click the attachment icon in the compose box. Select your image or video. Wait until the thumbnail displays in the compose area. Do not type alt text while the upload progress bar is visible.
2. Click the edit button on the uploaded media
   Hover over the thumbnail. A pencil icon appears in the top-right corner. Click it. The media editor opens with an Alt text field.
3. Type the alt text in the dedicated field
   Enter a clear description of the image. Keep it under 1,500 characters. Mastodon truncates longer descriptions in some views.
4. Click the Apply button or press Enter
   After typing, click the Apply button at the bottom of the editor. Do not press Escape or click outside the editor — that closes the editor without saving.
5. Verify the alt text appears below the thumbnail
   After closing the editor, look at the compose box. The thumbnail now shows a small ALT badge in the corner. This badge confirms the alt text is saved.
6. Submit the post using Ctrl+Enter
   Press Ctrl+Enter on Windows or Cmd+Enter on Mac. This keyboard shortcut submits the post without moving focus away from the compose box. Avoid clicking the Publish button if your cursor is still in the alt text editor.

Enabling the Advanced Web Interface for Persistent Alt Text Fields

The default Mastodon web interface hides the alt text field behind the edit button. The advanced web interface shows the field directly below each attachment. This reduces the chance of forgetting to add alt text.

1. Open Preferences
   Click the gear icon in the top-right corner of the Mastodon web interface. Select Preferences from the menu.
2. Navigate to Appearance
   In the left sidebar, click Appearance.
3. Enable Advanced web interface
   Check the box labeled Enable advanced web interface. Scroll down and click Save changes.
4. Reload the page
   Refresh your browser tab. The compose box now shows a text field labeled Describe for screen readers directly below each attachment.

If Mastodon Still Loses Alt Text After Following the Steps

Alt Text Missing After Editing a Post

Mastodon does not allow editing alt text on already published posts through the web interface. When you edit a post, the media editor opens, but any changes to alt text may not save. To fix this, delete the post and re-upload the media with the correct alt text using the steps above. The official Mastodon API supports editing alt text on published posts, but the web interface does not expose this endpoint. Use a third-party tool like the Mastodon REST API directly or a client such as Tusky (Android) that supports post editing with alt text changes.

Alt Text Disappears When Using a Third-Party App

Some third-party apps have a different upload flow. For example, the app may upload the image first and then ask for alt text in a separate screen. If you skip that screen, the app sends the post without alt text. Check the app’s documentation for its specific media upload process. As a workaround, open the Mastodon web interface on your phone’s browser and use the advanced web interface to add alt text before publishing.

Alt Text Truncated or Not Visible in Federated Posts

When your post federates to another Mastodon instance, the receiving server stores the alt text. If the receiving instance runs an older version of Mastodon (pre-3.0), it may not display alt text in the web interface. The text is still present in the API response. Users on that instance can access it through screen readers or by viewing the post’s raw JSON. There is no fix on your end. The instance admin must upgrade Mastodon.

Mastodon Alt Text Methods: Web Interface vs Mobile Apps

Item	Default Web Interface	Advanced Web Interface
Alt text field visibility	Hidden behind edit button	Always visible below each attachment
Number of clicks to add alt text	3 clicks (upload, edit, apply)	2 clicks (upload, type directly)
Keyboard shortcut to submit	Ctrl+Enter or Cmd+Enter	Ctrl+Enter or Cmd+Enter
Alt text badge on thumbnail	Shows ALT badge after saving	Shows ALT badge after typing

Mastodon’s official iOS and Android apps show the alt text field immediately after upload, similar to the advanced web interface. The apps do not require clicking an edit button. After uploading, type the description in the field labeled Alt text that appears below the image.

To ensure alt text is never missing, make it a habit to check for the ALT badge on the thumbnail before publishing. Enable the advanced web interface on desktop. On mobile, use the official app rather than a third-party client. If you manage a Mastodon instance, keep the software updated to the latest stable release so all users benefit from the full alt text API support.