Como corrigir o erro ‘Custom Emoji Failed to Load’ no Mastodon em postagens federadas

Ao navegar pela timeline federada do Mastodon, emojis personalizados de outras instâncias frequentemente aparecem como placeholders de imagem quebrados ou texto simples como :blobcat:. Isso acontece porque o Mastodon não baixa automaticamente os arquivos de emoji de servidores remotos. A mensagem de erro “Custom Emoji Failed to Load” indica que sua instância local não consegue recuperar ou exibir o arquivo de imagem do emoji do servidor de origem. Este artigo explica por que isso ocorre e fornece passos claros para corrigir o problema no seu próprio servidor Mastodon.

Por que os emojis personalizados não carregam em postagens federadas

O Mastodon armazena emojis personalizados como pequenos arquivos de imagem em cada instância. Quando um usuário de uma instância remota publica um emoji personalizado, seu servidor local deve baixar esse arquivo de emoji do servidor de origem e armazená-lo em cache localmente. Esse processo é executado como um job em segundo plano no Sidekiq. Se o download falhar, o emoji aparece como uma imagem quebrada ou como texto de shortcode simples.

Motivos comuns para a falha incluem:

Expiração do cache de mídia

O período padrão de retenção do cache de mídia do Mastodon é de 7 dias. Após esse período, os arquivos de emoji em cache são excluídos. Quando uma postagem federada referencia um emoji que estava em cache há mais de 7 dias, o servidor precisa baixá-lo novamente. Se o servidor de origem estiver offline ou lento, o download falha.

Jobs em segundo plano travados

As filas do Sidekiq gerenciam os downloads de emoji. Se uma fila ficar travada devido a pressão de memória ou um job corrompido, novos downloads de emoji nunca são concluídos. O emoji permanece em estado pendente e nunca aparece na postagem.

Bloqueio de domínio ou timeout do servidor

Se sua instância bloquear o domínio remoto (mesmo que parcialmente), ou se o servidor remoto estiver inacessível devido a problemas de rede, o arquivo de emoji não pode ser obtido. Isso acontece frequentemente com instâncias pequenas ou mal mantidas.

Passos para corrigir o carregamento de emojis personalizados em postagens federadas

Siga estes passos em ordem. Execute os dois primeiros passos pela interface de administração do Mastodon. Os passos 3 e 4 exigem acesso SSH ao seu servidor.

Passo 1: Aumentar o período de retenção do cache de mídia

1. Abra Administração > Configurações do Servidor
   Faça login como administrador. Clique em Preferências no canto superior direito e selecione Administração no menu à esquerda. Clique em Configurações do Servidor.
2. Vá para Retenção de Conteúdo
   Na página de Configurações do Servidor, clique na aba Retenção de Conteúdo. Esta aba controla por quanto tempo os arquivos de mídia são mantidos.
3. Defina a retenção do cache de mídia para 30 dias ou mais
   Encontre o campo Período de retenção do cache de mídia. Altere o valor de 7 para 30. Para instâncias movimentadas, defina para 60. Clique em Salvar alterações.

Passo 2: Limpar o cache de mídia manualmente

1. Abra Administração > Configurações do Servidor > Retenção de Conteúdo
   Siga o mesmo caminho do Passo 1.
2. Clique em Limpar cache de mídia
   Role para baixo até a seção Limpar cache de mídia. Clique no botão Limpar cache de mídia agora. Isso exclui todos os arquivos de mídia em cache, incluindo emojis. O Mastodon os baixará novamente na próxima solicitação.

Passo 3: Reiniciar as filas do Sidekiq via SSH

1. Conecte-se via SSH ao seu servidor Mastodon
   Abra um terminal. Execute ssh seuusuario@seuserver.com. Digite sua senha ou use sua chave SSH.
2. Mude para o usuário mastodon
   Execute su - mastodon. Isso garante que você execute comandos com as permissões corretas.
3. Reinicie o Sidekiq
   Execute systemctl --user restart sidekiq. Isso para e inicia todos os processos do Sidekiq. Aguarde 10 segundos e verifique o status da fila com systemctl --user status sidekiq. Procure por active (running).

Passo 4: Disparar manualmente o redownload de emojis via Rails Console

1. Abra o Rails console
   Enquanto estiver conectado via SSH como usuário mastodon, execute RAILS_ENV=production bin/rails c. Isso abre um ambiente Ruby interativo para o aplicativo Mastodon.
2. Encontre e remova entradas de cache de emoji obsoletas
   No prompt do Rails, digite: CustomEmoji.where.not(domain: nil).where(image_file_name: nil).destroy_all. Pressione Enter. Isso exclui todos os registros de emoji em cache que não possuem arquivo de imagem anexado. Digite exit para sair do console.
3. Reinicie o Sidekiq novamente
   Execute systemctl --user restart sidekiq para forçar o Mastodon a baixar novamente os emojis removidos.

Se o Mastodon ainda tiver problemas após a correção principal

Emoji personalizado ainda aparece como imagem quebrada em postagens específicas

Se apenas algumas postagens federadas têm emoji quebrado, o servidor de origem pode estar permanentemente offline. Você não pode corrigir isso da sua instância. O emoji nunca carregará a menos que o administrador remoto restaure o servidor. Nesse caso, peça aos seus usuários para recarregar a postagem após 24 horas. Se o problema persistir, o emoji está perdido.

Emoji carrega, mas aparece como ponto de interrogação ou quadrado em branco

Isso indica que o arquivo de emoji foi baixado, mas o formato da imagem não é suportado. O Mastodon suporta PNG, GIF e WebP. Se a instância remota fornecer um arquivo JPEG ou BMP, o Mastodon não consegue exibi-lo. Você não pode corrigir isso da sua instância. Entre em contato com o administrador remoto e peça para converter o emoji para um formato suportado.

Emoji carrega no desktop, mas não no aplicativo móvel

Aplicativos móveis de terceiros do Mastodon às vezes lidam com emojis personalizados de forma diferente. O aplicativo oficial do Mastodon para iOS e Android suporta emojis personalizados. Se você usa um aplicativo de terceiros, atualize-o para a versão mais recente. Se o problema continuar, mude para o aplicativo oficial.

Carregamento de emoji personalizado no Mastodon: correção do administrador vs. solução alternativa do usuário

Item	Correção do Administrador	Solução Alternativa do Usuário
Escopo	Afeta todos os usuários na instância	Afeta apenas o usuário individual
Esforço	Requer acesso SSH e comandos no servidor	Não precisa de acesso ao servidor
Permanência	Corrige a causa raiz permanentemente	Deve ser repetida após cada limpeza de cache
Exemplo	Aumentar retenção do cache de mídia para 60 dias	Limpar cache do navegador e recarregar a postagem
Limitação	Não corrige emojis de servidores permanentemente offline	Não corrige emoji quebrado para outros usuários

Agora você pode resolver o erro “Custom Emoji Failed to Load” em postagens federadas aumentando o período de retenção do cache de mídia e limpando entradas de cache obsoletas. Após aplicar as correções, monitore seu painel do Sidekiq para jobs travados. Para manutenção contínua, defina um lembrete mensal para verificar a página Administração > Sidekiq para filas com alta latência. Essa ação proativa evita falhas de carregamento de emoji antes que afetem seus usuários.