Índice

  1. Introducción

  2. ¿Por qué las actualizaciones pueden causar errores en Dolibarr?

  3. Preparación para una actualización: mejores prácticas

  4. Categorías de errores de actualización comunes

  5. Caso práctico 1: Desajuste del esquema de la base de datos

  6. Caso práctico 2: Incompatibilidad de versiones de PHP

  7. Caso práctico 3: Falta el archivo install.lock

  8. Caso práctico 4: Problemas de compatibilidad de módulos

  9. Caso práctico 5: Errores de permisos de archivos

  10. Caso práctico 6: Interfaz de usuario vacía o rota después de la actualización

  11. Caso práctico 7: Errores en los archivos de idioma

  12. Caso práctico 8: Trabajos cron y tareas programadas que fallan

  13. Análisis de registros: dónde buscar y qué observar

  14. Herramientas y scripts para ayudar en la resolución de problemas

  15. Cómo revertir de forma segura una actualización fallida

  16. Lecciones aprendidas y estrategias preventivas

  17. Recursos de apoyo comunitario y profesional

  18. Conclusión


1. Introducción

Dolibarr ERP/CRM se adopta ampliamente gracias a su flexibilidad y diseño modular. Sin embargo, como cualquier sistema complejo, las actualizaciones, especialmente las importantes, pueden generar problemas inesperados. Comprender, diagnosticar y resolver estos errores rápidamente es crucial para la continuidad del negocio. Este artículo explora escenarios reales de errores de actualización, sus causas raíz y soluciones estructuradas.


2. ¿Por qué las actualizaciones pueden causar errores en Dolibarr?

Cada nueva versión introduce cambios en:

  • Esquemas de bases de datos

  • Funciones y compatibilidad de PHP

  • API internas y estructuras de clases

  • Plantillas de IU y lógica de renderizado

  • Interfaces y configuraciones del módulo

Si estos cambios no van acompañados de una preparación y pruebas adecuadas, los errores serán casi inevitables.


3. Preparación para una actualización: mejores prácticas

Antes de actualizar:

  • Información su base de datos y sistema de archivos.

  • Pruebe la actualización en un entorno de ensayo.

  • Revise tu versión de PHP compatibilidad.

  • Verificar a terceros compatibilidad del módulo.

  • Confirmar la presencia de install.lock.

  • Personalizaciones de documentos para reimplementación.

Un enfoque basado en listas de verificación reduce drásticamente el riesgo.


4. Categorías de errores comunes de actualización

  • Errores de base de datos: desajuste de esquema, columnas faltantes

  • Errores fatales de PHP:clase/función no encontrada

  • Problemas de representación de la interfaz de usuario: diseños rotos, plantillas faltantes

  • Errores de idioma: traducciones faltantes

  • Problemas de acceso:errores de permisos después de cambios de archivo

  • Fallos del módulo: el código personalizado falla después de un cambio de núcleo

Cada categoría puede manifestarse con síntomas vagos como pantallas en blanco, errores 500 o fallas en la interfaz de usuario.


5. Caso práctico 1: Desajuste del esquema de la base de datos

Síntoma:

“Columna desconocida 'ref_ext' en 'lista de campos'” al ver facturas.

Causa principal:

Se omitió o falló la ejecución de un paso de migración de base de datos.

Resolución:

  • Comprobar /install/ directorio para el asistente de actualización.

  • Consulte el documento llx_const Tabla para seguimiento de versiones.

  • Vuelva a ejecutar la actualización desde /install/

  • Comparar manualmente llx_facture estructura utilizando el /install/mysql/ archivos


6. Caso práctico 2: Incompatibilidad de versiones de PHP

Síntoma:

Pantalla blanca o error "Función obsoleta".

Causa principal:

La versión de Dolibarr requiere una versión de PHP más nueva o más antigua que la actual.

Resolución:

  • Consulte la matriz de compatibilidad PHP oficial de Dolibarr

  • Actualice PHP si es demasiado antiguo o cambie a una versión inferior si es demasiado nueva

  • Asegúrese de que las extensiones PHP sean necesarias (pdo, gd, intl) están instalados


7. Caso práctico 3: Falta el archivo install.lock

Síntoma:

Dolibarr muestra el asistente de instalación en lugar del inicio de sesión.

Causa principal:

El install.lock El archivo fue eliminado o no se volvió a crear.

Resolución:

  • Crea un archivo vacío llamado install.lock en el directorio raíz

  • Establecer permisos correctos (644)

  • Bloquear /install/ directorio con .htaccess como medida secundaria


8. Caso práctico 4: Problemas de compatibilidad de módulos

Síntoma:

Los módulos personalizados ya no cargan ni generan excepciones.

Causa principal:

Cambios en los ganchos principales, estructuras de clases o firmas de API.

Resolución:

  • Comprueba la compatibilidad del módulo con tu versión de Dolibarr

  • Actualice el módulo si existe una versión más nueva

  • Deshabilitar módulos incompatibles temporalmente

  • Examinar los registros de errores para identificar funciones obsoletas


9. Caso práctico 5: Errores de permisos de archivos

Síntoma:

Errores de “Permiso denegado” durante la carga de archivos o la generación de PDF.

Causa principal:

Los permisos del sistema de archivos se restablecieron o están mal configurados después de la actualización.

Resolución:

  • Establecer htdocs y documents carpetas en las que el usuario web puede escribir

  • Usar chmod -R 755 y chown -R www-data:www-data

  • Confirmar conf.php es legible


10. Caso práctico 6: Interfaz de usuario en blanco o rota después de la actualización

Síntoma:

Se carga la pantalla de inicio de sesión, pero después de iniciar sesión la interfaz está en blanco.

Causa principal:

Incompatibilidad de tema o plantilla.

Resolución:

  • Cambiar a un tema predeterminado (Eldy) desde la base de datos directamente

  • Borrar caché de documents/temp/

  • Deshabilitar CSS o JavaScript personalizados


11. Caso práctico 7: Errores en archivos de idioma

Síntoma:

Etiquetas faltantes o sin traducir a pesar de la configuración del idioma.

Causa principal:

Archivos de idioma obsoletos o faltantes para nuevas funciones.

Resolución:

  • Ejecute el restablecimiento de caché de idioma a través de admin/tools.php?action=clear_langcache

  • Descargue el último paquete de idioma del portal de traducción de Dolibarr

  • Actualizar archivos manualmente en /langs/


12. Caso práctico 8: Trabajos cron y tareas programadas que fallan

Síntoma:

Las facturas, informes o tareas no se ejecutan según lo programado.

Causa principal:

Las URL de Cron cambiaron o cron_run_jobs.php El camino cambió.

Resolución:

  • Actualizar el trabajo cron para reflejar la nueva ruta de la versión de Dolibarr

  • Comprueba eso cron_run_jobs.php es ejecutable

  • Comprobar registros en documents/admin/cronjobs.log


13. Análisis de registros: dónde buscar y qué observar

Ubicaciones clave:

  • htdocs/conf/conf.php → configuración de base de datos y depuración

  • htdocs/logs/ (si está habilitado)

  • Registros de errores de Apache/Nginx

  • documents/admin/system.log

  • Consola del navegador para errores de JS

Activar $dolibarr_main_prod = 0; in conf.php para salida de error detallada (sólo para depuración).


14. Herramientas y scripts para ayudar en la resolución de problemas

  • dolibarr_dev_tools Repositorio GitHub

  • Herramientas de administración: Comprobador de integridad de la base de datos

  • Herramientas de diferenciación de SQL (por ejemplo, MySQL Workbench)

  • Comparación de archivos: diff, Meld, Más allá de toda comparación


15. Cómo revertir de forma segura una actualización fallida

  • Restaurar desde la copia de seguridad de la base de datos anterior a la actualización

  • Revertir el sistema de archivos desde el directorio comprimido de Dolibarr

  • Deshabilitar todos los módulos no esenciales

  • Utilice el control de versiones para los archivos de configuración y de módulo

Pruebe siempre la estrategia de reversión en fase de pruebas antes de aplicarla a producción.


16. Lecciones aprendidas y estrategias preventivas

  • Nunca actualice directamente en producción sin probar

  • Automatizar las copias de seguridad y los procesos de restauración

  • Mantener la documentación de los módulos instalados y sus versiones

  • Lea los registros de cambios de Dolibarr y los hilos del foro antes de actualizar

  • Suscríbete a las actualizaciones de versiones de Dolibarr para recibir alertas tempranas


17. Recursos de apoyo comunitario y profesional


18. Conclusión

Las actualizaciones de Dolibarr pueden ser complejas, especialmente en entornos altamente personalizados. Sin embargo, con una planificación adecuada, el conocimiento de los problemas más comunes y una solución de problemas estructurada, la mayoría de los errores se pueden resolver de forma rápida y segura. Esta guía le proporciona información práctica basada en casos concretos y pasos prácticos para garantizar que su próxima actualización sea fluida y sin complicaciones.