You have downloaded your Mastodon archive from your old instance and want to import it into a new account. An incomplete or corrupted archive can cause failed imports, missing posts, or broken media links. Mastodon creates a ZIP file containing JSON data, media files, and your avatar and header images. This article explains how to validate the archive structure, check for file integrity, and confirm the JSON content is correctly formatted before you start the import process.
Key Takeaways: Validating Your Mastodon Archive Before Import
- Check ZIP file size and contents: Ensure the archive is not zero bytes and contains expected folders like media_attachments and outbox.json.
- Validate JSON structure with a linter: Use an online JSON validator or command-line tool to confirm outbox.json is well-formed.
- Verify media file names match JSON references: Cross-check filenames in media_attachments against the mediaAttachment objects in outbox.json.
Why Validating a Mastodon Archive Matters
A Mastodon archive is a ZIP file generated by your old instance. It contains an outbox.json file with all your posts, plus folders for media attachments, avatar, and header images. If any of these files are missing, truncated, or corrupted, the import will fail partway through. You may end up with a partial timeline or broken media links that cannot be fixed later. Validation catches these issues before you attempt to import, saving time and frustration.
The archive is not encrypted. You can open the ZIP with any standard archive tool on Windows, macOS, or Linux. The key files to inspect are:
- outbox.json – Contains all your toots, their timestamps, content, and media references.
- media_attachments/ – Folder with images, videos, and other files attached to your posts.
- avatar.png or avatar.jpg – Your profile picture.
- header.png or header.jpg – Your profile header image.
Mastodon instances use ActivityPub standards for the JSON structure. The outbox.json file follows a specific schema with orderedItems and orderedItems arrays. A malformed JSON file will cause the import process to reject the entire archive.
Steps to Validate a Mastodon Archive
- Extract the ZIP file to a temporary folder
Right-click the archive in Windows Explorer and select Extract All. Choose a folder such as C:\temp\mastodon-archive. Do not extract directly to your Desktop to avoid clutter. After extraction, you should see outbox.json, a media_attachments folder, and optionally avatar and header files. - Check that outbox.json exists and is not empty
Open the extracted folder. Look for outbox.json. Right-click it and select Properties. The file size should be at least a few kilobytes. A zero-byte file indicates the archive failed during generation. If the file is missing, request a new archive from your old instance. - Validate the JSON syntax of outbox.json
Open a web browser and go to a JSON validator such as jsonlint.com. Copy the entire contents of outbox.json into the validator text area. Click Validate JSON. The tool will report any syntax errors such as missing commas, extra brackets, or unescaped characters. Fix these errors if possible, or request a new archive if the file is too damaged. - Verify the JSON structure matches Mastodon expectations
Scroll through the validated JSON. Look for a top-level key called “orderedItems” or “items”. Each item should have an “object” key with “type”: “Note” for regular posts. Confirm that media attachments are referenced with an “attachment” array containing objects with “url” fields. If the structure looks completely different from a standard Mastodon outbox, the archive may be from a different platform or a corrupted export. - Count the number of posts in outbox.json
Use a text editor with line counting or a JSON viewer. The number of items in the orderedItems array should roughly match the number of public posts you made on your old instance. A large discrepancy suggests missing data. You can compare this count against your old instance profile page if you still have access. - Check media_attachments folder contents
Open the media_attachments folder. It should contain subfolders named by year and month, such as 2024/01. Inside each subfolder, there should be image or video files. Verify that the total number of files matches the number of media references in outbox.json. A mismatch means some media files are missing from the archive. - Cross-reference filenames between JSON and filesystem
Search in outbox.json for a sample media URL. For example, find a line like “url”: “https://old-instance.example/system/media_attachments/files/110/123/456/789/123/original/image.jpg”. The last part of the path after “original/” should match a filename inside media_attachments. If the file is not present, that media will be missing after import. - Test opening a few media files
Double-click a few random image files in media_attachments to confirm they open correctly in your default image viewer. Corrupted files may show an error or a blank image. If multiple files are corrupted, request a new archive from the old instance. - Verify avatar and header files exist
Look for avatar.png, avatar.jpg, header.png, or header.jpg in the root of the extracted folder. These files are optional but should be present if you had a custom profile picture or header. If missing, your new account will use default placeholder images after import.
Common Issues During Archive Validation
outbox.json Contains Only a Few Posts
If the archive shows far fewer posts than expected, the export may have been limited to public posts only. Mastodon archives typically include all your public posts, but private or direct messages are excluded. Check your old instance export settings. Some instances allow selecting a date range for the archive. If you used a date filter, the archive only contains posts from that period.
Media Files Are Missing Entirely
The media_attachments folder might be empty or absent. This happens when the archive generation process fails to include media due to disk space limits or timeouts on the server. Contact your old instance admin and request a new archive. Alternatively, you can manually download media from your old profile if you still have access, but this is time-consuming for large accounts.
JSON Validation Reports Syntax Errors
Syntax errors in outbox.json usually result from an interrupted archive download. The ZIP file may have been partially written. Delete the corrupted archive and download it again from your old instance. Ensure your internet connection is stable during the download. If the error persists, the instance server may have generated a faulty archive. Ask the admin to regenerate it.
Filenames in JSON Do Not Match Files on Disk
This mismatch occurs when the archive was generated while new media was being uploaded. The JSON references files that were not yet saved to disk at the time of archiving. Unfortunately, there is no fix for this. You must request a new archive from the instance after the upload activity has settled. Alternatively, you can manually add the missing media files if you have copies elsewhere.
| Item | Valid Archive | Corrupted or Incomplete Archive |
|---|---|---|
| outbox.json file size | At least several kilobytes | Zero bytes or less than 1 KB |
| JSON syntax | Passes JSON validator without errors | Shows syntax errors or fails to parse |
| Number of posts | Matches your public post count on old instance | Significantly fewer posts than expected |
| media_attachments folder | Contains subfolders with image and video files | Empty folder or missing entirely |
| Media file integrity | Opens correctly in image viewer or media player | Shows errors or blank content |
| Avatar and header files | Present if you had custom images | Missing even though you had custom images |
Validating your Mastodon archive takes about 10 minutes. You can now confidently import your data into a new account knowing that posts and media will transfer correctly. After a successful validation, proceed to Preferences > Import and Export > Import Archive on your new Mastodon instance. For large archives over 100 MB, consider using the command-line tool tootctl to avoid browser timeout errors.