Mastodon Import Failed: ‘Invalid CSV’ Error and How to Fix

You uploaded a CSV file to Mastodon to import followers or blocks, and the server rejected it with an Invalid CSV error. This error usually means the file structure does not match what Mastodon expects. The problem often lies in incorrect column headers, extra quote characters, or stray text outside the data rows.

Mastodon requires CSV files to have a specific header row and a simple comma-separated format. Files exported from other social networks or edited in spreadsheet software often introduce formatting that Mastodon cannot parse. This article explains the exact CSV format Mastodon expects and provides step-by-step fixes to correct your file.

After reading this guide, you will be able to identify why your CSV file is invalid, reformat it correctly, and successfully complete the import in Mastodon.

Why Mastodon Rejects CSV Files with the Invalid CSV Error

Mastodon imports follow lists, block lists, and domain blocks through CSV files. The import system expects a very strict format. The file must be plain text with no byte order mark (BOM), no extra whitespace around values, and no quoted fields unless the field contains a comma.

The most common root cause is the header row. Mastodon looks for the exact header Account address,Show boosts for follow imports. If the header says Account Address with a capital A, or Account address,show boosts with lowercase s, the server returns Invalid CSV.

Another frequent cause is the presence of double quotes around every field. Mastodon only accepts quoted fields when the field itself contains a comma. For example, a username like "@user@example.com" is fine, but "@user@example.com" with quotes around every row is not. Spreadsheet programs like Excel or Google Sheets often export every cell with quotes, which breaks the import.

Finally, hidden characters such as carriage returns, line feeds that are not consistent, or a BOM at the start of the file can cause the parser to fail. Files saved with UTF-8 BOM encoding are a common culprit when exporting from Windows Notepad or Excel.

Steps to Fix the Invalid CSV Error and Complete the Import

1. Open the CSV file in Notepad or another plain text editor
   Do not use Excel or Google Sheets for editing. Right-click the file, select Open with, and choose Notepad. This shows the raw text without any hidden formatting.
2. Check the first row for the exact header
   For a follow import, the first line must be Account address,Show boosts exactly. For a block import, the header must be Account address only. If you see any extra spaces, different capitalization, or additional columns, edit the header to match exactly.
3. Remove all double quotation marks from the file
   Use Notepad’s Replace function. Press Ctrl+H. In Find what, type a double quote mark. Leave Replace with empty. Click Replace All. This strips every quote character. Mastodon will re-add quotes automatically where needed during import.
4. Remove any trailing commas from each line
   Look for lines that end with a comma after the last value. Delete those trailing commas. Each line should end with the last value followed by a line break.
5. Save the file with UTF-8 encoding without BOM
   In Notepad, go to File > Save As. At the bottom, set Encoding to UTF-8. Do not choose UTF-8 with BOM. Name the file with a .csv extension and save it to your desktop.
6. Test the file by importing a small subset
   Create a test CSV with only two or three accounts. Upload it to Mastodon via Preferences > Import and Export > Import. Select the correct type (Following, Blocking, etc.) and click Upload. If this succeeds, your main file still has an issue. If it also fails, the format is still wrong.
7. Re-upload the corrected CSV to Mastodon
   Go to Preferences > Import and Export > Import. Choose the type that matches your CSV. Click Browse and select your corrected file. Click Upload. Mastodon will process the file and show a success message or a list of failed entries.

Fixing CSV Files Exported from Twitter or Other Platforms

If you are migrating from Twitter, the exported CSV has a different structure. Twitter exports include columns like username, name, and bio. Mastodon ignores those columns but still requires the correct header row. You must delete all columns except Account address and Show boosts. Then rename the header to match Mastodon’s format.

Open the Twitter CSV in Notepad. Remove everything except the two required columns. Ensure the header row is Account address,Show boosts. Remove any extra text at the top of the file, such as a summary line or export date. Save the file as UTF-8 without BOM.

If the Invalid CSV Error Persists After Fixing the File

File contains a BOM that Notepad cannot remove

Some text editors, including older versions of Notepad, add a BOM when saving with UTF-8 encoding. To remove the BOM, open the file in a more capable editor like Visual Studio Code or Sublime Text. In Visual Studio Code, click the encoding indicator at the bottom of the window (it usually says UTF-8 with BOM). Select Save with Encoding and choose UTF-8. This removes the BOM.

CSV file has more than 5000 rows and times out

Mastodon’s import process can handle large files, but very large imports may time out. If your file has more than 5000 rows, split it into smaller chunks of 1000 rows each. Upload each chunk separately. Use a tool like split CSV online or manually copy rows into separate files.

Import succeeds but no followers appear

This happens when the account addresses in the CSV are not valid Mastodon handles. Each address must be in the format @username@instance.domain. Check that every row contains a full handle. Partial handles like @username without a domain will be ignored. Also verify that the accounts exist and are not suspended.

Mastodon CSV Import: Expected Format vs Common Mistakes

Item	Correct Format	Common Mistake
Header row for following	Account address,Show boosts	account address,show boosts or Account,Show
Header row for blocking	Account address	Account address, with trailing comma
Account address format	@user@example.com	user@example.com without the leading @
Quotation marks	Only around fields containing commas	Quotes around every field
File encoding	UTF-8 without BOM	UTF-8 with BOM or ANSI
Line endings	Unix-style LF only	Windows CR+LF causing extra blank lines

Now you can inspect any CSV file, correct the header and encoding, and import it into Mastodon without seeing the Invalid CSV error. The next time you need to migrate followers, use the export function from your old account to get a file that already matches the expected format. For advanced troubleshooting, enable developer tools in your browser and check the network response from the import API endpoint — it often returns a more detailed error message than the web interface shows.