Cómo corregir el error ‘custom emoji failed to load’ en publicaciones federadas de Mastodon

Cuando navegas por la línea de tiempo federada de Mastodon, los emojis personalizados de otras instancias a menudo aparecen como marcadores de posición de imagen rota o como texto plano como :blobcat:. Esto ocurre porque Mastodon no descarga automáticamente los archivos de emoji de servidores remotos. El mensaje de error “Custom Emoji Failed to Load” indica que tu instancia local no puede recuperar o mostrar el archivo de imagen del emoji desde el servidor de origen. Este artículo explica por qué ocurre esto y proporciona pasos claros para solucionar el problema en tu propio servidor de Mastodon.

Por qué los emojis personalizados no se cargan en publicaciones federadas

Mastodon almacena los emojis personalizados como pequeños archivos de imagen en cada instancia. Cuando un usuario de una instancia remota publica un emoji personalizado, tu servidor local debe descargar ese archivo de emoji desde el servidor de origen y almacenarlo en caché localmente. Este proceso se ejecuta como un trabajo en segundo plano en Sidekiq. Si la descarga falla, el emoji se muestra como una imagen rota o como texto de código corto.

Las razones comunes del fallo incluyen:

Caducidad de la caché de medios

El período de retención de caché de medios predeterminado de Mastodon es de 7 días. Después de eso, los archivos de emoji en caché se eliminan. Cuando una publicación federada hace referencia a un emoji que se almacenó en caché hace más de 7 días, el servidor debe volver a descargarlo. Si el servidor de origen está fuera de línea o es lento, la descarga falla.

Trabajos en segundo plano estancados

Las colas de Sidekiq manejan las descargas de emojis. Si una cola se atasca debido a presión de memoria o un trabajo corrupto, las nuevas descargas de emojis nunca se completan. El emoji permanece en estado pendiente y nunca aparece en la publicación.

Bloqueo de dominio o tiempo de espera del servidor

Si tu instancia bloquea el dominio remoto (incluso parcialmente), o si el servidor remoto es inalcanzable debido a problemas de red, el archivo de emoji no se puede obtener. Esto suele ocurrir con instancias pequeñas o mal mantenidas.

Pasos para corregir la carga de emojis personalizados en publicaciones federadas

Sigue estos pasos en orden. Realiza los dos primeros pasos desde la interfaz de administración de Mastodon. Los pasos 3 y 4 requieren acceso SSH a tu servidor.

Paso 1: Extiende el período de retención de caché de medios

1. Abre Administración > Configuración del servidor
   Inicia sesión como administrador. Haz clic en Preferencias en la esquina superior derecha y luego selecciona Administración en el menú izquierdo. Haz clic en Configuración del servidor.
2. Ve a Retención de contenido
   En la página de Configuración del servidor, haz clic en la pestaña Retención de contenido. Esta pestaña controla cuánto tiempo se conservan los archivos de medios.
3. Establece la retención de caché de medios en 30 días o más
   Encuentra el campo Período de retención de caché de medios. Cambia el valor de 7 a 30. Para instancias con mucho tráfico, establécelo en 60. Haz clic en Guardar cambios.

Paso 2: Limpia la caché de medios manualmente

1. Abre Administración > Configuración del servidor > Retención de contenido
   Sigue la misma ruta que en el Paso 1.
2. Haz clic en Limpiar caché de medios
   Desplázate hacia abajo hasta la sección Limpiar caché de medios. Haz clic en el botón etiquetado Limpiar caché de medios ahora. Esto elimina todos los archivos de medios en caché, incluidos los emojis. Mastodon los volverá a descargar en la próxima solicitud.

Paso 3: Reinicia las colas de Sidekiq a través de SSH

1. Conéctate por SSH a tu servidor de Mastodon
   Abre una terminal. Ejecuta ssh youruser@yourserver.com. Ingresa tu contraseña o usa tu clave SSH.
2. Cambia al usuario de Mastodon
   Ejecuta su - mastodon. Esto asegura que ejecutes comandos con los permisos correctos.
3. Reinicia Sidekiq
   Ejecuta systemctl --user restart sidekiq. Esto detiene e inicia todos los procesos de Sidekiq. Espera 10 segundos y luego verifica el estado de la cola con systemctl --user status sidekiq. Busca active (running).

Paso 4: Activa manualmente la redescarga de emojis a través de la consola de Rails

1. Abre la consola de Rails
   Mientras estás conectado por SSH al servidor como usuario de Mastodon, ejecuta RAILS_ENV=production bin/rails c. Esto abre un entorno interactivo de Ruby para la aplicación de Mastodon.
2. Encuentra y purga las entradas de caché de emojis obsoletas
   En el indicador de Rails, escribe: CustomEmoji.where.not(domain: nil).where(image_file_name: nil).destroy_all. Presiona Enter. Esto elimina todos los registros de emojis en caché que no tienen un archivo de imagen adjunto. Escribe exit para salir de la consola.
3. Reinicia Sidekiq nuevamente
   Ejecuta systemctl --user restart sidekiq para forzar a Mastodon a redescargar los emojis purgados.

Si Mastodon aún tiene problemas después de la solución principal

El emoji personalizado aún se muestra como imagen rota en publicaciones específicas

Si solo ciertas publicaciones federadas tienen emojis rotos, el servidor de origen puede estar permanentemente fuera de línea. No puedes solucionar esto desde tu instancia. El emoji nunca se cargará a menos que el administrador remoto restaure su servidor. En este caso, pide a tus usuarios que recarguen la publicación después de 24 horas. Si el problema persiste, el emoji se pierde.

El emoji se carga pero aparece como un signo de interrogación o un cuadrado en blanco

Esto indica que el archivo de emoji se descargó pero el formato de imagen no es compatible. Mastodon admite PNG, GIF y WebP. Si la instancia remota sirve un archivo JPEG o BMP, Mastodon no puede mostrarlo. No puedes solucionar esto desde tu instancia. Contacta al administrador remoto y pídele que convierta el emoji a un formato compatible.

El emoji se carga en el escritorio pero no en la aplicación móvil

Las aplicaciones móviles de Mastodon de terceros a veces manejan los emojis personalizados de manera diferente. La aplicación oficial de Mastodon para iOS y Android admite emojis personalizados. Si usas una aplicación de terceros, actualízala a la última versión. Si el problema continúa, cambia a la aplicación oficial.

Carga de emojis personalizados en Mastodon: solución de administrador vs. solución de usuario

Elemento	Solución de administrador	Solución de usuario
Alcance	Afecta a todos los usuarios de la instancia	Afecta solo al usuario individual
Esfuerzo	Requiere acceso SSH y comandos de servidor	No se necesita acceso al servidor
Permanencia	Corrige la causa raíz permanentemente	Debe repetirse después de cada limpieza de caché
Ejemplo	Extender la retención de caché de medios a 60 días	Limpiar la caché del navegador y recargar la publicación
Limitación	No puede corregir emojis de servidores permanentemente fuera de línea	No corrige emojis rotos para otros usuarios

Ahora puedes resolver el error “Custom Emoji Failed to Load” en publicaciones federadas extendiendo el período de retención de caché de medios y limpiando las entradas de caché obsoletas. Después de aplicar las correcciones, monitorea tu panel de Sidekiq para detectar trabajos estancados. Para el mantenimiento continuo, establece un recordatorio mensual para revisar la página Administración > Sidekiq para detectar colas con alta latencia. Este paso proactivo evita fallas en la carga de emojis antes de que afecten a tus usuarios.