Dolibarr Update: Checkliste und Versionen 16 bis 24

Viele Unternehmen bleiben jahrelang auf derselben Dolibarr-Version, aus Angst, dass danach nichts mehr funktioniert. Die Angst ist berechtigt, zielt aber meist auf das Falsche. Fast nie geht Dolibarr selbst kaputt. Es ist das, was Sie drumherum ergänzt haben.

Um das zu prüfen, wurden 45 freie Module auf Test-Instanzen installiert und dann tatsächlich aktualisiert, Version für Version, bis zur 24: insgesamt 280 Versionswechsel. Die Vergleichsinstanz ohne zusätzliches Modul lief von 16 bis 24 ohne einen einzigen fatalen Fehler. Alle gefundenen Ausfälle kamen aus dem Code externer Module. Und 13 dieser Module hatten schon vor jedem Update einen fatalen Fehler, ohne dass es jemand bemerkt hatte.

Das Risiko liegt also an vier Stellen, immer denselben:

• externe Module, also alles im Ordner custom/;
• die PHP-Version Ihres Servers;
• berechnete oder bedingte Zusatzfelder und ihre Filter;
• versteckte Einstellungen und die Variablen Ihrer E-Mail- und Dokumentvorlagen, von denen einige umbenannt wurden.

Warum gerade jetzt

Die E-Rechnung macht aktuelle Versionen zur Pflicht. In Deutschland müssen Unternehmen seit Januar 2025 E-Rechnungen empfangen können, die Pflicht zum Versand folgt 2027 und 2028. In Frankreich gilt die Empfangspflicht seit September 2026. Die aktuellen Module für elektronische Rechnungen setzen neuere Dolibarr-Versionen voraus: Wer noch auf einer alten Version arbeitet, kommt um ein Update nicht herum.

Vorher: die Checkliste

1. Notieren Sie Ihre genaue Dolibarr-Version und Ihre PHP-Version. Beide stehen in den Systeminformationen der Administrationswerkzeuge.
2. Vergleichen Sie Ihre PHP-Version mit der Tabelle unten. Unterhalb des Minimums bietet der Update-Assistent gar nichts an. Oberhalb der höchsten vorgesehenen Version zeigt er nur eine Warnung: Es kann funktionieren, aber niemand hat es für Sie getestet.
3. Listen Sie Ihre externen Module auf, also alles im Ordner custom/. Prüfen Sie für jedes, ob eine Version als kompatibel mit Ihrer Zielversion angegeben ist, und besorgen Sie sie vor dem Start. Das ist die häufigste Ausfallursache.
4. Prüfen Sie Ihre Zusatzfelder: berechnete Felder, ihre Anzeigebedingungen und ihre Filter. Mehrere alte Schreibweisen werden nicht mehr akzeptiert (Details je Version weiter unten).
5. Suchen Sie die versteckten Einstellungen, die Sie gesetzt haben, in der erweiterten Konfiguration: Einige wurden umbenannt, eine hat sogar ihre Bedeutung umgekehrt.
6. Prüfen Sie Ihre E-Mail-Vorlagen und Ihre ODT-Dokumentvorlagen: Einige Ersetzungsvariablen gibt es nicht mehr.
7. Machen Sie eine vollständige Sicherung und prüfen Sie, dass Sie sie wiederherstellen können. Vollständig heißt: die Datenbank, der Dokumentenordner, die Datei conf/conf.php und der Ordner custom/. Eine Sicherung, die nie wiederhergestellt wurde, ist nur eine Hoffnung.
8. Proben Sie das Update an einer Kopie, bevor Sie die echte Instanz anfassen. Nur so sehen Sie die Ausfälle vor Ihren Benutzern.

Um bei dieser Checkliste Zeit zu sparen, erledigt das kostenlose Modul Update-Bereitschaftsprüfung die meisten dieser Prüfungen, ohne etwas zu verändern: Es liest den Code jedes externen Moduls gegen die Zielversion, prüft PHP, die Datenbank, berechnete Felder und ODT-Vorlagen und liefert einen Bericht. Es ersetzt weder die Sicherung noch den Test auf einer Kopie.

Währenddessen: der Ablauf

Sie müssen nicht jede Zwischenversion installieren: Man spielt direkt die Dateien der Zielversion ein. Die Datenbank dagegen durchläuft jeden Schritt: Der Update-Assistent bietet die Migrationen einzeln an (16 auf 17, dann 17 auf 18 und so weiter), und Sie müssen alle der Reihe nach ausführen.

Unter Docker mit dem offiziellen Image ist es anders: Das automatische Update überspringt Migrationen, wenn man mehrere Versionen auf einmal wechselt. Lesen Sie zuerst Dolibarr unter Docker aktualisieren.

Per SSH, ohne Web-Assistenten, lassen sich dieselben Migrationen über die Kommandozeile starten, mit einer Falle, die den zweiten Schritt ohne jede Fehlermeldung blockiert: siehe Dolibarr über die Kommandozeile aktualisieren.

1. Informieren Sie die Benutzer: Während des Updates darf niemand in Dolibarr arbeiten.
2. Machen Sie die oben beschriebene vollständige Sicherung.
3. Ersetzen Sie die Dolibarr-Dateien durch die der neuen Version, ohne conf/conf.php, den Ordner custom/ oder den Dokumentenordner zu überschreiben.
4. Löschen Sie die Datei install.lock im Dokumentenordner. Solange sie existiert, lässt sich der Assistent nicht öffnen, und das ist so gewollt.
5. Öffnen Sie die Adresse Ihres Dolibarr mit /install/ dahinter und führen Sie jeden angebotenen Migrationsschritt bis zur Zielversion aus.
6. Legen Sie install.lock am Ende wieder an. Ohne diese Datei könnte jeder die Installation neu starten.
7. Öffnen Sie die Masken, die Sie täglich nutzen: eine Rechnung, ein Angebot, die PDF-Erzeugung, die Masken Ihrer externen Module.

Wenn sich etwas nicht mehr öffnet

Eine weiße Seite oder ein Fehler 500 direkt nach dem Update kommt in den allermeisten Fällen von einem externen Modul. Das PHP-Fehlerprotokoll nennt die betroffene Datei: Liegt sie in custom/, haben Sie den Verursacher.

Lässt sich die Modulverwaltung nicht mehr öffnen, kann man das Modul direkt in der Datenbank deaktivieren. Passen Sie das Tabellenpräfix (standardmäßig llx_) und den Modulnamen an, und sehen Sie sich zuerst an, was die Abfrage betrifft:

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

Für den Weg zurück stellen Sie Datenbank und Dateien immer gemeinsam wieder her. Alte Dateien auf einer bereits migrierten Datenbank werden von Dolibarr nicht blockiert, und genau das ist gefährlich: Alles scheint zu funktionieren, bis eine Maske in eine Spalte schreibt, die sich geändert hat.

Die Versionstabelle 16 bis 24

PHP mindestens ist die Version, unterhalb derer der Update-Assistent nichts anbietet. Die höchste vorgesehene PHP-Version ist nur eine Warnschwelle: Darüber zeigt Dolibarr einen Hinweis, blockiert aber nicht. Ist eines der entfernten Module bei Ihnen noch aktiv, suchen Sie vor dem Update einen Ersatz.

Was sich ändert, Version für Version

Hier stehen nur Änderungen, die ein Unternehmen betreffen können, das Dolibarr nutzt, nicht solche, die nur die Entwickler des Kerns angehen.

• 16: Sensible Aktionen verlangen jetzt ein Sicherheitstoken, auch in Links. Ein altes Modul, das es nicht mitgibt, bekommt seine Schaltflächen verweigert. Trigger mit dem Namen …_UPDATE heißen jetzt …_MODIFY: Ein Modul oder eine Automatisierung, die darauf wartet, löst nicht mehr aus.
• 17: In berechneten Zusatzfeldern heißt das aktuelle Objekt $objectoffield. Die versteckte Einstellung MAIN_LIST_ALLOW_NOTES heißt jetzt MAIN_LIST_HIDE_NOTES.
• 18: Die Version, die auf unserem Prüfstand die meisten externen Module lahmgelegt hat (4 von 6 Ausfällen), weil Methoden des Kerns ihre Form geändert haben. Sensible Schlüssel in den Einstellungsseiten, etwa API-Schlüssel, werden jetzt verschlüsselt gespeichert.
• 19: Die offiziellen Docker-Images wechseln von PHP 8.1 auf PHP 8.2. In den Bedingungen von Zusatzfeldern stehen die Variablen $soc und $right nicht mehr zur Verfügung.
• 20: Filter von Zusatzfeldern vom Typ Verknüpfung müssen in der neuen universellen Filtersyntax (feld:=:wert) geschrieben werden, nicht mehr in SQL. Ein Modul, das ein nicht deklariertes Array Eintrag für Eintrag befüllt ($this->liste['schlüssel'] = …), verliert diese Werte. Das steht nicht im ChangeLog: auf unserem Prüfstand festgestellt, dann nachgestellt.
• 21: Die Vorlagenvariable __MEMBER_CIVILITY__ heißt jetzt __MEMBER_TITLE__. Die PHP-Erweiterung json wird Pflicht.
• 22: Die versteckte Einstellung STOCK_ALLOW_NEGATIVE_TRANSFER wird umgekehrt und in STOCK_DISALLOW_NEGATIVE_TRANSFER umbenannt. GETPOST ist in Bedingungen von Zusatzfeldern verboten.
• 23: $obj funktioniert in berechneten Feldern und Bedingungen nicht mehr; schreiben Sie $objectoffield, verlangt seit der 17. Das ChangeLog kündigt auch das Ende von $object an, es funktioniert in 23.0.4, 24.0.1 und 24.0.2 aber noch: Ersetzen Sie es jetzt. Verkettung ist in berechneten Feldern standardmäßig abgeschaltet.
• 24: Die Variable __MYCOUNTRY_ID__ entfällt, ersetzt durch __MYCOMPANY_COUNTRY_ID__. Die API-Anmeldung mit Benutzername und Passwort ist standardmäßig aus.
• 24, Falle beim unveränderbaren Protokoll (Modul BlockedLog), wenn Sie es seit einer alten Version nutzen: Liegt dessen Schlüssel noch im Klartext in der Datenbank, lässt sich in 24.0.0 oder 24.0.1 keine Rechnung mehr freigeben (Meldung #40153). Die Fehlermeldung zeigt dann den Schlüssel im Klartext: Teilen Sie keine Screenshots davon. Die 24.0.2, am 2. Oktober 2026 auf SourceForge veröffentlicht, am 4. Oktober auf dolibarr.org aber noch nicht angekündigt, behebt diesen Fall. Getestet: Die Freigabe funktioniert wieder, und der unveränderte Schlüssel wird bei der ersten freigegebenen Rechnung neu verschlüsselt. Der Update-Assistent rührt ihn nicht an. Bis zur Ankündigung der 24.0.2 lassen Sie diesen Punkt vor dem Wechsel auf 24 prüfen.

Wie diese Angaben ermittelt wurden

• Die PHP-Versionen stammen aus dem Installationsprogramm jeder Version (install/check.php), nicht aus der Dokumentation, die manchmal abweicht.
• Die entfernten Module stammen aus dem Vergleich der Kernmodule, Version für Version.
• Die Änderungen stammen aus dem offiziellen ChangeLog von Dolibarr.
• Die Ausfallzahlen stammen von 45 freien Modulen, die unter Docker tatsächlich aktualisiert wurden, mit dem offiziellen Assistenten, auf den offiziellen Images von Dolibarr 16 bis 24.

Diese Tabelle wird mit jeder neuen Version aktualisiert.

Hilfe holen

Wenn Sie diesen Eingriff an Ihrem Rechnungswerkzeug lieber nicht selbst durchführen, ist genau dafür das Paket Abgesichertes Update da: Ihre Instanz wird kopiert, das Update wird an der Kopie geprobt, bis es durchläuft, Rechnungen, PDFs und Module werden geprüft, und erst dann wird umgestellt. Wenn Sie zuerst wissen möchten, wo Sie stehen, prüft die Diagnose für 90 € Ihre Version, Ihr PHP und Ihre Module, und ihr Preis wird angerechnet, wenn Sie das Paket danach bestellen.

Siehe auch

• Dolibarr sichern und wiederherstellen
• Dolibarr Fehler 500 oder weiße Seite
• Die Datei install.lock