Guía de Actualización de Chatwoot v4.9 a v4.11.1: Resolviendo Inconsistencias y Registros Huérfanos

Actualizar una plataforma de comunicación omnicanal como Chatwoot en un entorno Dockerizado suele ser un proceso directo, pero los saltos de versión (especialmente hacia la v4.11.x) pueden presentar retos interesantes. En esta sesión, documentamos cómo resolver un error crítico de "pantalla vacía" tras la migración.

El Problema: El Error de "Método Indefinido para Nil"

Tras realizar el docker compose pull y ejecutar las migraciones iniciales, la interfaz de Chatwoot no cargaba los mensajes. Los logs del contenedor de Rails revelaron el siguiente fallo:

ActionView::Template::Error (undefined method 'additional_attributes' for nil)

Este error ocurre cuando el sistema intenta renderizar una conversación que ha perdido su relación con un contacto (registros huérfanos). La versión 4.11 introduce cambios en la API que requieren una integridad total en estas asociaciones.

Lección 1: Limpieza de Registros Huérfanos

Cuando una actualización falla debido a registros inconsistentes, el comando estándar destroy_all de Rails puede fallar si intenta validar asociaciones en tablas que aún no se han creado físicamente.

La solución técnica: Utilizar delete_all a través de la consola de Rails. Este comando ejecuta una instrucción SQL directa, saltándose las validaciones del modelo y permitiendo limpiar la base de datos incluso en estados inconsistentes.

# Accediendo a la consola de Rails
docker compose exec rails bundle exec rails c

# Borrado directo de conversaciones sin contacto asociado
Conversation.where.not(contact_id: Contact.pluck(:id)).delete_all

Lección 2: Sincronización entre Rails y PostgreSQL

Un hallazgo crítico fue detectar que Rails marcaba las migraciones como completadas (up), pero las tablas (como captain_assistant_responses) no existían físicamente en PostgreSQL. Esto genera un "falso positivo" en el estado del sistema.

Cómo repararlo:

1. Entrar a la base de datos y eliminar manualmente los registros de la tabla schema_migrations correspondientes a las versiones fallidas.
2. Forzar a Rails a re-ejecutar dichas migraciones:

# Comando para forzar la creación física de tablas faltantes
docker compose exec rails bundle exec rails db:migrate

Lección 3: El papel crucial de Redis

Incluso después de arreglar la base de datos, la interfaz puede seguir mostrando datos erróneos. Chatwoot utiliza Redis para gestionar caché de sesiones y contadores de conversaciones. Sin una limpieza de Redis, la aplicación intentará buscar IDs que ya no existen.

Comando esencial:

docker compose exec redis redis-cli flushall

Checklist para futuras actualizaciones

1. Migraciones: Utilizar db:chatwoot_prepare en lugar de un simple migrate para asegurar que todas las tareas de configuración se ejecuten.
2. Integridad: Verificar la existencia de registros huérfanos antes de dar por terminada la actualización.
3. Caché: Realizar un flush de Redis y limpiar la caché del navegador para cargar los nuevos activos de la v4.11.
4. Permisos: Asegurar que el volumen de storage/ tenga los permisos adecuados para que Rails pueda escribir nuevos archivos adjuntos.