Falha na Importação do Mastodon: Erro ‘CSV Inválido’ e Como Corrigir

Você enviou um arquivo CSV para o Mastodon para importar seguidores ou bloqueios, e o servidor o rejeitou com um erro de CSV inválido. Esse erro geralmente significa que a estrutura do arquivo não corresponde ao que o Mastodon espera. O problema geralmente está em cabeçalhos de coluna incorretos, aspas extras ou texto solto fora das linhas de dados.

O Mastodon exige que arquivos CSV tenham uma linha de cabeçalho específica e um formato simples separado por vírgulas. Arquivos exportados de outras redes sociais ou editados em planilhas geralmente introduzem formatação que o Mastodon não consegue interpretar. Este artigo explica o formato CSV exato que o Mastodon espera e fornece correções passo a passo para ajustar seu arquivo.

Após ler este guia, você conseguirá identificar por que seu arquivo CSV é inválido, reformatá-lo corretamente e concluir a importação no Mastodon com sucesso.

Por que o Mastodon Rejeita Arquivos CSV com o Erro de CSV Inválido

O Mastodon importa listas de seguidores, listas de bloqueio e bloqueios de domínio por meio de arquivos CSV. O sistema de importação espera um formato muito rigoroso. O arquivo deve ser texto simples, sem marca de ordem de byte (BOM), sem espaços extras ao redor dos valores e sem campos entre aspas, a menos que o campo contenha uma vírgula.

A causa raiz mais comum é a linha de cabeçalho. O Mastodon procura o cabeçalho exato Account address,Show boosts para importações de seguidores. Se o cabeçalho disser Account Address com A maiúsculo, ou Account address,show boosts com s minúsculo, o servidor retorna CSV inválido.

Outra causa frequente é a presença de aspas duplas ao redor de todos os campos. O Mastodon só aceita campos entre aspas quando o campo em si contém uma vírgula. Por exemplo, um nome de usuário como "@usuario@exemplo.com" é aceitável, mas "@usuario@exemplo.com" com aspas em todas as linhas não é. Programas de planilha como Excel ou Google Sheets geralmente exportam cada célula com aspas, o que quebra a importação.

Por fim, caracteres ocultos como retornos de carro, quebras de linha inconsistentes ou um BOM no início do arquivo podem fazer o parser falhar. Arquivos salvos com codificação UTF-8 com BOM são um culpado comum ao exportar do Bloco de Notas ou Excel do Windows.

Passos para Corrigir o Erro de CSV Inválido e Concluir a Importação

1. Abra o arquivo CSV no Bloco de Notas ou outro editor de texto simples
   Não use Excel ou Google Sheets para editar. Clique com o botão direito no arquivo, selecione Abrir com e escolha Bloco de Notas. Isso mostra o texto bruto sem formatação oculta.
2. Verifique se a primeira linha contém o cabeçalho exato
   Para importação de seguidores, a primeira linha deve ser Account address,Show boosts exatamente. Para importação de bloqueios, o cabeçalho deve ser apenas Account address. Se você vir espaços extras, capitalização diferente ou colunas adicionais, edite o cabeçalho para corresponder exatamente.
3. Remova todas as aspas duplas do arquivo
   Use a função Substituir do Bloco de Notas. Pressione Ctrl+H. Em Localizar, digite uma aspa dupla. Deixe Substituir por vazio. Clique em Substituir Tudo. Isso remove todos os caracteres de aspas. O Mastodon readicionará aspas automaticamente quando necessário durante a importação.
4. Remova todas as vírgulas finais de cada linha
   Procure linhas que terminam com uma vírgula após o último valor. Exclua essas vírgulas finais. Cada linha deve terminar com o último valor seguido de uma quebra de linha.
5. Salve o arquivo com codificação UTF-8 sem BOM
   No Bloco de Notas, vá em Arquivo > Salvar Como. Na parte inferior, defina Codificação como UTF-8. Não escolha UTF-8 com BOM. Nomeie o arquivo com extensão .csv e salve na área de trabalho.
6. Teste o arquivo importando um subconjunto pequeno
   Crie um CSV de teste com apenas duas ou três contas. Envie para o Mastodon via Preferências > Importar e Exportar > Importar. Selecione o tipo correto (Seguindo, Bloqueando, etc.) e clique em Enviar. Se isso funcionar, seu arquivo principal ainda tem um problema. Se também falhar, o formato ainda está errado.
7. Reenvie o CSV corrigido para o Mastodon
   Vá em Preferências > Importar e Exportar > Importar. Escolha o tipo que corresponde ao seu CSV. Clique em Procurar e selecione seu arquivo corrigido. Clique em Enviar. O Mastodon processará o arquivo e mostrará uma mensagem de sucesso ou uma lista de entradas com falha.

Corrigindo Arquivos CSV Exportados do Twitter ou Outras Plataformas

Se você está migrando do Twitter, o CSV exportado tem uma estrutura diferente. As exportações do Twitter incluem colunas como username, name e bio. O Mastodon ignora essas colunas, mas ainda exige a linha de cabeçalho correta. Você deve excluir todas as colunas, exceto Account address e Show boosts. Em seguida, renomeie o cabeçalho para corresponder ao formato do Mastodon.

Abra o CSV do Twitter no Bloco de Notas. Remova tudo, exceto as duas colunas necessárias. Certifique-se de que a linha de cabeçalho seja Account address,Show boosts. Remova qualquer texto extra no topo do arquivo, como uma linha de resumo ou data de exportação. Salve o arquivo como UTF-8 sem BOM.

Se o Erro de CSV Inválido Persistir Após Corrigir o Arquivo

O arquivo contém um BOM que o Bloco de Notas não consegue remover

Alguns editores de texto, incluindo versões antigas do Bloco de Notas, adicionam um BOM ao salvar com codificação UTF-8. Para remover o BOM, abra o arquivo em um editor mais capaz, como Visual Studio Code ou Sublime Text. No Visual Studio Code, clique no indicador de codificação na parte inferior da janela (geralmente diz UTF-8 with BOM). Selecione Salvar com Codificação e escolha UTF-8. Isso remove o BOM.

O arquivo CSV tem mais de 5000 linhas e expira o tempo limite

O processo de importação do Mastodon pode lidar com arquivos grandes, mas importações muito grandes podem exceder o tempo limite. Se seu arquivo tiver mais de 5000 linhas, divida-o em partes menores de 1000 linhas cada. Envie cada parte separadamente. Use uma ferramenta como split CSV online ou copie manualmente as linhas para arquivos separados.

A importação é bem-sucedida, mas nenhum seguidor aparece

Isso acontece quando os endereços de conta no CSV não são handles válidos do Mastodon. Cada endereço deve estar no formato @usuário@instância.domínio. Verifique se cada linha contém um handle completo. Handles parciais como @usuário sem domínio serão ignorados. Verifique também se as contas existem e não estão suspensas.

Importação de CSV no Mastodon: Formato Esperado vs Erros Comuns

Item	Formato Correto	Erro Comum
Linha de cabeçalho para seguir	Account address,Show boosts	account address,show boosts ou Account,Show
Linha de cabeçalho para bloquear	Account address	Account address, com vírgula final
Formato do endereço da conta	@usuário@exemplo.com	usuário@exemplo.com sem o @ inicial
Aspas	Apenas ao redor de campos que contêm vírgulas	Aspas em todos os campos
Codificação do arquivo	UTF-8 sem BOM	UTF-8 com BOM ou ANSI
Finais de linha	Apenas LF (Unix)	CR+LF (Windows) causando linhas em branco extras

Agora você pode inspecionar qualquer arquivo CSV, corrigir o cabeçalho e a codificação e importá-lo para o Mastodon sem ver o erro de CSV inválido. Na próxima vez que precisar migrar seguidores, use a função de exportação da sua conta antiga para obter um arquivo que já corresponda ao formato esperado. Para solução de problemas avançada, ative as ferramentas de desenvolvedor no seu navegador e verifique a resposta de rede do endpoint da API de importação — geralmente ela retorna uma mensagem de erro mais detalhada do que a interface web mostra.