Actualizar Dolibarr sin romper nada: versiones 16 a 24

Muchas empresas se quedan años en la misma versión de Dolibarr por miedo a romperlo todo. Ese miedo está justificado, pero suele apuntar al blanco equivocado. Casi nunca es Dolibarr el que se rompe. Es lo que usted ha añadido alrededor.

Para comprobarlo, se instalaron 45 módulos libres en instancias de prueba de Dolibarr, que luego se actualizaron de verdad, versión tras versión, hasta la 24: 280 cambios de versión en total. El Dolibarr de control, sin ningún módulo añadido, pasó de la 16 a la 24 sin un solo error fatal. Todas las averías encontradas venían del código de los módulos externos. Y 13 de esos módulos ya tenían un error fatal antes de cualquier actualización, sin que nadie se hubiera dado cuenta.

El riesgo está, por tanto, en cuatro sitios, siempre los mismos:

• los módulos externos, los de la carpeta custom/;
• la versión de PHP de su servidor;
• los campos adicionales calculados o condicionales, y sus filtros;
• los ajustes ocultos y las variables de sus plantillas de correo y de documentos, algunas de las cuales han cambiado de nombre.

Antes: la lista de control

1. Anote su versión exacta de Dolibarr y su versión de PHP. Las dos aparecen en la información del sistema, dentro de las herramientas de administración.
2. Compare su PHP con la tabla de más abajo. Por debajo del mínimo, el asistente de actualización no le propondrá nada. Por encima del máximo previsto, solo muestra un aviso: puede funcionar, pero nadie lo ha probado por usted.
3. Haga la lista de sus módulos externos, es decir, todo lo que hay en la carpeta custom/. Para cada uno, compruebe que existe una versión anunciada como compatible con la versión de destino, y consígala antes de empezar. Es la causa de avería número uno.
4. Revise sus campos adicionales calculados, sus condiciones de visualización y sus filtros. Varias formas antiguas de escribirlos ya no se aceptan (detalle versión por versión más abajo).
5. Localice los ajustes ocultos que haya definido en la configuración avanzada: algunos han cambiado de nombre, e incluso uno ha invertido su sentido.
6. Revise sus plantillas de correo y sus plantillas de documentos ODT: algunas variables de sustitución han desaparecido.
7. Haga una copia de seguridad completa, y compruebe que sabe restaurarla. Completa quiere decir: la base de datos, la carpeta de documentos, el archivo conf/conf.php y la carpeta custom/. Una copia de seguridad que nunca se ha restaurado no es más que una esperanza.
8. Ensaye la actualización en una copia antes de tocar la instancia real. Es la única manera de ver las averías antes que sus usuarios.

Para ganar tiempo con esta lista, el módulo gratuito Listo para la actualización hace la mayoría de estas comprobaciones sin modificar nada: lee el código de cada módulo externo frente a la versión de destino, comprueba PHP, la base de datos, los campos calculados y las plantillas ODT, y le entrega un informe. No sustituye ni a la copia de seguridad ni al ensayo en una copia.

Durante: el procedimiento

No hace falta instalar cada versión intermedia: se instalan directamente los archivos de la versión de destino. En cambio, la base de datos sí pasa por todas las etapas: el asistente de actualización le propone las migraciones una a una (de 16 a 17, luego de 17 a 18, y así sucesivamente), y hay que lanzarlas todas, en orden.

En Docker, con la imagen oficial, es distinto: la actualización automática se salta migraciones si se pasan varias versiones de golpe. Lea primero Upgrading Dolibarr in Docker (en inglés).

Por SSH, sin el asistente web, las mismas migraciones se lanzan en línea de comandos, con una trampa que bloquea la segunda etapa sin ningún error: vea Upgrading Dolibarr from the command line (en inglés).

1. Avise a los usuarios: nadie debe trabajar en Dolibarr durante la operación.
2. Haga la copia de seguridad completa descrita más arriba.
3. Sustituya los archivos de Dolibarr por los de la nueva versión, sin sobrescribir conf/conf.php, la carpeta custom/ ni la carpeta de documentos.
4. Borre el archivo install.lock, que está en la carpeta de documentos. Mientras exista, el asistente se niega a abrirse, y es a propósito.
5. Abra la dirección de su Dolibarr seguida de /install/ y lance cada etapa de migración propuesta, hasta la versión de destino.
6. Vuelva a crear install.lock al final. Sin él, cualquiera podría relanzar la instalación.
7. Abra las pantallas que usa a diario: una factura, un presupuesto, la generación de un PDF, las pantallas de sus módulos externos.

Si algo ya no se abre

Una página en blanco o un error 500 justo después de una actualización viene, en la inmensa mayoría de los casos, de un módulo externo. El registro de errores de PHP indica el archivo culpable: si está en custom/, ya tiene al responsable.

Si la pantalla de módulos ya no se abre, se puede desactivar el módulo directamente en la base de datos. Adapte el prefijo de las tablas (llx_ por defecto) y el nombre del módulo, y mire primero lo que la consulta va a tocar:

SELECT name, value FROM llx_const WHERE name LIKE 'MAIN_MODULE_NOMDUMODULE%';
DELETE FROM llx_const WHERE name LIKE 'MAIN_MODULE_NOMDUMODULE%';

Para volver atrás, restaure siempre la base de datos y los archivos juntos. Dolibarr no bloquea unos archivos antiguos colocados sobre una base ya migrada, y eso es precisamente lo peligroso: todo parece funcionar, hasta el día en que una pantalla escribe en una columna que ha cambiado.

La tabla de las versiones 16 a 24

El PHP mínimo es aquel por debajo del cual el asistente de actualización no propone nada. El PHP más reciente previsto es solo un umbral de aviso: por encima, Dolibarr muestra una alerta pero no bloquea. Si alguno de los módulos retirados sigue activo en su instalación, búsquele un sustituto antes de la actualización.

Lo que cambia, versión por versión

Aquí solo se recogen los cambios que pueden afectar a una empresa que usa Dolibarr, no los que solo conciernen a los desarrolladores del núcleo.

• 16: las acciones sensibles exigen ahora un token de seguridad, también en los enlaces. Un módulo antiguo que no lo transmite ve sus botones rechazados. Los disparadores llamados …_UPDATE pasan a ser …_MODIFY: un módulo o una automatización que los esperaba deja de dispararse.
• 17: en los campos adicionales calculados, el objeto actual se escribe $objectoffield. Los ajustes ocultos MAIN_LIST_ALLOW_PUBLIC_NOTES y MAIN_LIST_ALLOW_PRIVATE_NOTES pasan a ser MAIN_LIST_HIDE_PUBLIC_NOTES y MAIN_LIST_HIDE_PRIVATE_NOTES; la migración los renombra sola.
• 18: es la versión que más módulos externos rompió en nuestro banco de pruebas (4 averías de 6), por métodos del núcleo cuya firma cambió. Las claves sensibles de las páginas de configuración, como las claves de API, se cifran ahora en la base de datos.
• 19: las imágenes Docker oficiales pasan de PHP 8.1 a PHP 8.2. En las condiciones de los campos adicionales, las variables $soc y $right ya no están disponibles.
• 20: los filtros de los campos adicionales de tipo enlace deben escribirse con la nueva sintaxis de filtro universal (campo:=:valor), y ya no en SQL. Un módulo que rellena elemento por elemento un array que no ha declarado ($this->lista['clave'] = …) pierde esos valores. Este punto no figura en el registro de cambios: lo vimos en nuestro banco de pruebas y luego lo reprodujimos.
• 21: la variable __MEMBER_CIVILITY__ de las plantillas pasa a ser __MEMBER_TITLE__. La extensión json de PHP se vuelve imprescindible.
• 22: el ajuste oculto STOCK_ALLOW_NEGATIVE_TRANSFER se sustituye por STOCK_DISALLOW_NEGATIVE_TRANSFER. Trampa: el módulo Stock pone él mismo STOCK_ALLOW_NEGATIVE_TRANSFER a 1, lo que permite movimientos de stock en negativo. Tras la migración, quedan prohibidos: la migración añade la prohibición para la entidad 0, que Dolibarr también lee. Comprobado el 3 de noviembre de 2026 en una migración real de la 21.0.4 a la 22.0.5. Si a veces vende o transfiere sin stock, compruébelo en la copia antes de cambiar. GETPOST queda prohibido en las condiciones de los campos adicionales.
• 23: $obj deja de funcionar en los campos calculados y en las condiciones; escriba $objectoffield, que se pide desde la 17. El registro de cambios anuncia también el fin de $object, pero sigue funcionando en 23.0.4, 24.0.1 y 24.0.2: sustitúyalo sin esperar. La concatenación está desactivada por defecto en los campos calculados.
• 24: la variable __MYCOUNTRY_ID__ desaparece, sustituida por __MYCOMPANY_COUNTRY_ID__. La conexión a la API con usuario y contraseña está cortada por defecto.
• 24, trampa del registro inalterable (módulo BlockedLog), si lo usa desde una versión antigua: si su clave se quedó sin cifrar en la base de datos, ya no se puede validar ninguna factura en 24.0.0 ni en 24.0.1 (incidencia #40153). El mensaje de error muestra entonces la clave en claro: no difunda capturas de pantalla de ese mensaje. La 24.0.2, publicada el 2 de octubre de 2026, corrige este caso. Probado: la validación vuelve a funcionar, y la clave, sin cambios, se vuelve a cifrar con la primera factura validada. El asistente de actualización, en cambio, no la toca. Si pasa a la 24, vaya por tanto directamente a la 24.0.2, no a la 24.0.0 ni a la 24.0.1.

Cómo se ha establecido esta información

• Las versiones de PHP vienen del instalador de cada versión (install/check.php), no de la documentación, que a veces difiere.
• Los módulos retirados vienen de comparar los módulos del núcleo, versión por versión.
• Los cambios vienen del registro oficial de cambios de Dolibarr.
• Las cifras de averías vienen de 45 módulos libres actualizados de verdad en Docker, con el asistente oficial, sobre las imágenes oficiales de Dolibarr 16 a 24.

Esta tabla se mantendrá al día con cada nueva versión.

Pedir ayuda

Si prefiere no hacer esta operación usted mismo en su herramienta de facturación, es exactamente el servicio Actualización segura: se copia su instancia, la actualización se ensaya en la copia hasta que funciona, se comprueban sus facturas, sus PDF y sus módulos, y solo entonces se hace el cambio. Si antes quiere saber en qué punto está, el diagnóstico de 90 € revisa su versión, su PHP y sus módulos, y su precio se descuenta del servicio si lo encarga después. El servicio se presta en español, inglés, francés o alemán.

Lea también

• Instalar Dolibarr con Docker Compose
• Error «Dolibarr config file content seems to be not correctly defined»
• Back up and restore Dolibarr (en inglés)
• Dolibarr error 500 or blank page (en inglés)
• The install.lock file (en inglés)