JTL Wawi Update schlägt fehl: Die häufigsten Fehler und wie du sie löst

Auf einen Blick

• ✓Die häufigsten Update-Abbrüche in JTL Wawi haben vier Ursachen: zu wenig Speicherplatz auf dem SQL-Server, eine veraltete SQL-Server-Version, Duplikate in der Datenbank und beschädigte Artikelbilder. Alle vier lassen sich beheben, wenn man sie kennt.
• ✓Unsere Regel: erst manuell sichern, dann Update starten. Die automatische Datensicherung in neueren Wawi-Versionen hilft, aber eine externe Kopie der eazybusiness-Datenbank ist die einzige echte Rückfallebene.
• ✓Der Simulations-Modus zeigt Datenbankfehler im Trockenlauf, bevor sie live passieren — wir aktivieren ihn bei jedem Kundenprojekt. Für den Sprung auf Wawi 2.0.x gilt außerdem ein eigener Update-Pfad: nicht direkt von 1.11.x auf 2.0.1 springen. Bug WAWI-87918 betrifft alle 2.0.x-Versionen (Connector-API bricht ab) und wird erst in 2.1 gefixt.

Als JTL Service Partner Gold aus Ahrensfelde bei Berlin begleiten wir Update-Prozesse für über 300 aktive Kunden deutschlandweit. Was wir dabei immer wieder sehen: Update-Fehler entstehen selten durch das Update selbst. Fast immer liegt das Problem in der Grundlage. Ein SQL-Server mit zu wenig Speicher, keine Backup-Routine oder eine Datenbankstruktur, die seit Jahren nicht gewartet wurde. Wer das vor dem Update sauber macht, hat danach keine bösen Überraschungen.

Aus JTL-Forum-Auswertungen und unseren eigenen Projektdaten zeigt sich: Bei einem relevanten Teil aller größeren Wawi-Updates tritt mindestens eine Unterbrechung auf. Die Ursachen verteilen sich nicht gleichmäßig. Datenbankprobleme sind für den Großteil der Fälle verantwortlich, dahinter kommen Infrastruktur-Probleme auf dem SQL-Server und fehlerhafte Daten in der eazybusiness-Datenbank. Große Versionssprünge bringen dabei mehr Risiko mit als Patch-Updates innerhalb einer Versionslinie.

Aus unseren Projektdaten: Wenn ein Kunde kein manuelles Backup hatte und in einen Update-Fehler lief, dauerte die Wiederherstellung bis zu dreimal länger als bei Kunden mit sauberer Backup-Strategie. Das automatische Wawi-Backup schützt die Datenbank. Aber nur, wenn der SQL-Server genug Speicherplatz hat, um es überhaupt anzulegen.

Die häufigsten Auslöser für Update-Abbrüche in JTL Wawi, sortiert nach Häufigkeit aus unserem Praxisbetrieb:

• →SQL-Server Speicherplatz erschöpft: Der SQL Server Express hat eine Datenbankgrößen-Begrenzung. Wächst die eazybusiness-Datenbank darüber hinaus, schlägt das Update fehl. Fehlermeldung: ‚Eine neue Seite für die eazybusiness-Datenbank konnte nicht belegt werden, weil in der Dateigruppe PRIMARY nicht genügend Speicherplatz verfügbar ist.‘
• →Veraltete SQL-Server-Version: Jede neue Wawi-Version bringt Mindestanforderungen an die SQL-Server-Version mit. Wer diese nicht erfüllt, bekommt beim Datenbankupdate eine Fehlermeldung, die auf fehlende Kompatibilität hinweist.
• →Doppelte Schlüssel in der Datenbank: Durch manuelle Eingriffe oder Sync-Fehler entstehen Duplikate in Datenbanktabellen. Fehlermeldung: ‚Verletzung der PRIMARY KEY-Einschränkung. Ein doppelter Schlüssel kann in das dbo.tWawiAttributSprache-Objekt nicht eingefügt werden.‘ (Quelle: WAWI-23509)
• →Defekte Artikelbilder: Update-Skripte, die Artikelbilder migrieren, brechen ab wenn einzelne Bilder beschädigt sind. JTL hat das Problem mit Ticket WAWI-51461 dokumentiert und behoben. Ältere Wawi-Installationen, die nie aktualisiert wurden, können trotzdem noch betroffen sein.
• →Benutzerrechte fehlen: Der SQL-Benutzer, unter dem das Update läuft, hat nicht die notwendigen Rechte, um Datenbankobjekte zu ändern. Das Update bricht dann ohne klare Fehlermeldung ab.
• →eazybusiness-Datenbankfehler beim Sprung auf Wawi 2.0.x: Beim Direktsprung von 1.11.x auf 2.0.1 tritt ein spezifischer Fehler auf: ‚Der TYPE_spkundeUpdate-Datentyp für die Spalte, den Parameter oder die Variable Nr. 1 wurde nicht gefunden.‘ Ein Händler im JTL-Forum berichtete: ‚Update auf 2.0.1 schlägt direkt bei der eazybusiness-Datenbank fehl — kein Fortschritt, kein hilfreicher Log-Eintrag.‘ JTL hat keinen Einzel-Hotfix veröffentlicht. Empfohlener Update-Pfad: erst auf 1.11.7, dann auf 2.0.0, dann auf 2.0.1. Nie direkt von 1.11.x auf 2.0.1 springen. Für diesen Update-Pfad empfehlen wir, einen JTL Service Partner einzubeziehen.
• →API v1-Fehler nach Update auf Wawi 2.0.x: Connector-Nutzer und Drittsystem-Anbindungen berichten nach dem Update auf 2.0.x: Aufträge lassen sich nicht mehr über die API anlegen. Fehlermeldung: ‚TaxRate: The field TaxRate must be between 0 and 2147483647. Discount: The field Discount must be between 0 and 100.‘ Die gemeldeten Werte (TaxRate=7, Discount=0) sind korrekt — der Fehler liegt im API-Validierungsmodul von 2.0.x. JTL hat den Bug als WAWI-87918 bestätigt. Fix wird in Version 2.1 ausgeliefert. Sofortmaßnahme: JTL-Support-Ticket mit Verweis auf WAWI-87918 öffnen.

Die zentrale Erkenntnis: Kein Update-Fehler fällt vom Himmel. Alle bekannten Abbruch-Ursachen lassen sich vor dem Update erkennen, mit einer einfachen Checkliste und einem Blick auf Datenbankgröße, SQL-Version und Backup-Status.

Aus unserer Arbeit mit Händlern unterschiedlicher Größe haben sich zwei Muster herauskristallisiert, die den Großteil der Update-Probleme ausmachen:

1

Das Update bricht mittendrin ab

Der häufigste Fall: Das Update läuft an, die Fortschrittsanzeige stoppt irgendwo zwischen 40 und 80 Prozent, die Fehlermeldung ist technisch. ‚Unbehandelte Ausnahme‘ oder ‚Fehler beim Befehl‘. Die Datenbank steckt in einem Zwischenzustand. Wawi startet nicht mehr, das Update lässt sich nicht einfach neu starten.

Was dahinter steckt: Das Update-Skript hat angefangen, Datenbankstrukturen zu verändern, und ist dabei auf einen Fehler gestoßen. Duplikat, Speicherproblem oder fehlendes Recht. Mit aktivem Simulations-Modus stellt Wawi auf den letzten Backup-Punkt zurück. Ohne Simulation bleibt die Datenbank im Fehlerzustand. Dann hilft nur das externe Backup.

2

Das Update läuft durch, Wawi zeigt danach Fehler

Seltener, aber schwieriger: Das Update meldet ‚Fertig‘, Wawi startet neu, und dann stimmt etwas nicht. Artikel haben falsche Lieferzeiten, Mengenangaben auf Rechnungen zeigen plötzlich ‚ Stk‘ hinter der Zahl, der Shop-Sync meldet Verbindungsfehler. Ein Händler im JTL-Forum beschrieb es so: ‚Nach dem Update 1.1.4.13 ist bei der Mengenangabe zusätzlich zur Zahl ein Stk-Kürzel aufgetaucht, das vorher nicht da war.‘

Ursache: Datenmigrations-Skripte haben Feldinhalte verändert oder Standardwerte gesetzt, die mit vorhandenen Konfigurationen kollidieren. Der JTL-Shop-Sync bricht nach einem großen Versionssprung ab, wenn der Verbindungstest einen neuen API-Endpunkt erwartet, der noch nicht konfiguriert ist. Das Wichtige: Diese Fehler sind keine Datenverluste. Das sind Konfigurationsprobleme, die sich beheben lassen.

Kein Produktionsstillstand bei Update-Fehlern

Wer vor dem Update ein externes Datenbankbackup hat, ist im Fehlerfall innerhalb von Minuten wieder am Ausgangszustand. Aus unserer Projektpraxis: Kunden mit sauberer Backup-Routine waren bei Update-Problemen in unter 30 Minuten wieder produktionsfähig. Ohne externes Backup kann die Wiederherstellung je nach Datenbankgröße und SQL-Server-Zustand erheblich länger dauern. Vorausgesetzt, der SQL-Server kann die automatische Wawi-Sicherung überhaupt noch anlegen.

Frühwarnung durch den Simulations-Modus

Der Update-Assistent von JTL Wawi bietet einen Simulations-Modus. Das Update wird komplett durchgespielt, die Datenbank gesichert und am Ende wieder zurückgespielt. Fehler, die im Trockenlauf auftreten, zeigen genau, welche Datenbankobjekte das Problem verursachen. Vlarom aktiviert diesen Modus bei jedem Update-Projekt. Ein überschaubarer Zusatzaufwand, der im Ernstfall Stunden an Fehlersuche spart.

Die folgende Reihenfolge haben wir aus echten Update-Projekten abgeleitet. Die Checkliste gilt für Minor-Updates genauso wie für größere Versionssprünge. Wer jeden Schritt in dieser Reihenfolge abarbeitet, schließt die häufigsten Fehlerursachen vor dem Update aus.

Vor jedem Update: Datenbankgröße der eazybusiness in SQL Server Management Studio prüfen. Bei SQL Server Express zusätzlich schauen, ob die Größe unter 10 GB liegt. SQL-Server-Version mit ‚SELECT @@VERSION‘ abfragen und gegen die Mindestanforderung der Ziel-Wawi-Version abgleichen. Laut JTL-Guide zur Datensicherung sollten Backups nie auf derselben Festplatte liegen wie die Originaldatenbank. Das gilt auch für die Wawi-interne Sicherung. Wer hier Probleme findet, behebt sie vor dem Update.

JTL Wawi legt während des Updates automatisch eine Datenbanksicherung an, sofern die Option nicht deaktiviert wurde. Das reicht aber nicht als alleinige Absicherung. Wir legen zusätzlich einen manuellen Export über Wawi > Start > Datenbank > Datenbankexport an und speichern ihn auf einem anderen Laufwerk. Der Schritt ist schnell erledigt und ist die einzige Rückfallebene, wenn der SQL-Server beim automatischen Backup ebenfalls in den Fehler läuft.

Im Update-Assistenten den Simulations-Modus aktivieren. Der Assistent führt dann einen vollständigen Trockenlauf durch. Er sichert die Datenbank, spielt alle Update-Skripte durch und stellt am Ende alles zurück. Fehler, die in der Simulation auftreten, zeigen die genaue Ursache inklusive Tabellenname und SQL-Befehl. Mit dieser Info lässt sich gezielt nachbessern. Laut JTL-Guide zum Update-Prozess startet das echte Datenbankupdate erst, wenn die Simulation sauber durchgelaufen ist.

PRIMARY KEY-Verletzungen: Duplikate in der Datenbank bereinigen. Dafür den SQL-Befehl aus dem Fehlerlog nehmen, die betroffene Tabelle prüfen und doppelte Einträge entfernen. Speichermangel: Nicht benötigte Daten archivieren oder SQL-Server Express auf Standard upgraden. Benutzerrechte: Den SQL-Benutzer, unter dem Wawi läuft, auf ‚db_owner‘ der eazybusiness-Datenbank setzen. Erst wenn die Simulation sauber durchläuft, startet das echte Update.

Das eigentliche Update über Dashboard oder Installationspaket starten. Nach dem Update alle kritischen Funktionen prüfen: Artikel-Stammdaten öffnen, einen Testauftrag anlegen, Shop-Sync-Verbindungstest laufen lassen, Rechnungsdruck testen. Bei angebundenem JTL-Shop den Verbindungstest im Shop-Modul ausführen und bei Fehlern den Connector-Endpunkt im JTL-Backend prüfen. Mengenangaben auf Rechnungen und Lieferzeiten in der Artikel-Vorschau kontrollieren.

Das Update ist durchgelaufen, Wawi startet — aber Worker, Lizenz oder Connector machen Probleme? Die folgenden fünf Fehlertypen treten nach einem erfolgreichen JTL Wawi Update am häufigsten auf.

Aus unserer Betreuung nach JTL Wawi Updates zeigt sich ein klares Bild: Die meisten Probleme sind keine Update-Bugs, sondern Konfigurationsprobleme, die das Update sichtbar macht. Ein großer Versionssprung bringt dabei mehr dieser Probleme zutage als ein kleines Patch-Update innerhalb derselben Versionslinie, weil solche Sprünge mehr Systemkomponenten berühren.

Aus unseren Projektdaten: Bei großen Versionssprüngen — also wenn mehrere Hauptversionen auf einmal übersprungen werden — treten Post-Update-Probleme deutlich häufiger auf als bei Minor-Updates. Gleichzeitig sind diese Probleme fast immer behebbar, wenn man sie systematisch angeht. Der entscheidende Unterschied ist nicht ob ein Problem auftritt, sondern wie schnell man es einem der bekannten Fehlertypen zuordnen kann.

Diese fünf Fehlertypen sehen wir nach einem JTL Wawi Update am häufigsten:

• →Worker startet nicht oder bleibt im Fehler-Zustand: Der JTL Worker Service läuft als Windows-Dienst und wird beim Update nicht automatisch neu gestartet. Nach einem größeren Versionssprung kommt es vor, dass der Dienst in einen Fehlerzustand gerät oder mit einer veralteten Konfiguration startet. Erkennbar: Im Worker-Status-Fenster unter Admin erscheinen rote Einträge, einzelne Aufgaben laufen in einer Schleife oder der Worker bleibt dauerhaft in einem Wartezustand.
• →Lizenz wird als ungültig oder nicht erkannt angezeigt: Nach einem Update auf eine neue Hauptversion muss die Lizenz mit dem JTL-Kundencenter-Account übereinstimmen. Wenn die Lizenz mit einem anderen Account verknüpft ist, oder wenn der Lizenz-Cache lokal veraltet ist, erscheint ein Fehler in der Verkaufskanalverwaltung. Das ist kein tatsächlicher Lizenzverlust — die Lizenz ist vorhanden. Das Problem liegt in der Zuordnung. (Bekanntes Problem: WAWI-81768, dokumentiert im JTL Issue-Tracker)
• →Datenbankverbindung schlägt beim Start fehl: Wenn beim ersten Start nach dem Update die Meldung erscheint, dass keine Verbindung zur eazybusiness-Datenbank hergestellt werden kann, liegt das häufig an einem SQL Server Express, der den Neustart nach dem Update noch nicht vollständig durchgeführt hat. Ein zweites häufiges Muster: Die SQL-Anmeldedaten wurden beim Update zurückgesetzt oder der Datenbankbenutzer hat nicht mehr die nötigen Rechte.
• →Druckvorlagen zeigen Fehler oder falsche Ausgabe: JTL Wawi nutzt DotLiquid-Templates für Rechnungen, Lieferscheine und andere Belege. Nach einem Update können Druckvorlagen brechen, wenn das Update interne Feldreferenzen verändert hat. Typisches Symptom: Positionen erscheinen mehrfach, Mengenangaben haben plötzlich ein Kürzel (z.B. ‚Stk‘) das vorher nicht da war, oder die gesamte Vorlage rendert leer. Ein Händler im JTL-Forum: ‚Nach dem Update wurden alle Positionen dreifach auf dem Beleg ausgegeben, sowohl auf der gedruckten als auch auf der PDF-Version.‘
• →Connector-Synchronisation zum Shop bricht ab: Nach einem größeren Wawi-Update erwartet der Connector einen kompatiblen Gegenpunkt im Shop-System. Wenn die Connector-Version im JTL-Shop noch auf dem alten Stand ist, schlägt der Verbindungstest fehl. JTL zeigt in diesem Fall die Meldung: ‚Synchronisation mit Webshop nicht möglich. Die Shop-URL verweist nicht auf einen gültigen Shop. Bitte Connector-Konfiguration prüfen.‘ Das bedeutet in den meisten Fällen: Connector auf Shop-Seite muss ebenfalls aktualisiert werden.

Die zentrale Beobachtung aus der Praxis: Keiner dieser fünf Fehlertypen ist ein Datenverlust. Alle sind Konfigurationsprobleme, die sich mit dem richtigen Diagnoseweg beheben lassen. Wer das Muster kennt, braucht dafür selten mehr als eine Stunde.

Die Frage die wir am häufigsten hören: „Vorher hat alles funktioniert — warum jetzt auf einmal nicht mehr?“ Die Antwort folgt zwei Mustern:

1

Das Update macht bestehende Probleme sichtbar

Viele Konfigurationsprobleme in JTL Wawi schlummern unbemerkt in der Datenbank oder in Systemdiensten, weil sie im laufenden Betrieb keine direkten Fehlermeldungen erzeugen. Erst wenn ein Update neue Schnittstellen, neue Datenbankstrukturen oder neue API-Endpunkte einführt, prallen diese alten Konfigurationen auf die neuen Erwartungen.

Konkret: Ein SQL Server Express der 8 GB Datenbankgröße hat, läuft monatelang stabil. Nach dem Update auf eine neue Hauptversion scheitert das Datenbankupgrade an der 10-GB-Grenze. Das Problem war schon da — das Update hat es nur aufgedeckt. Gleiches gilt für Connector-Versionen, die nie aktualisiert wurden, und für Druckvorlagen mit veralteten Feldreferenzen.

2

Das Update ändert Abhängigkeiten zwischen Systemkomponenten

JTL Wawi ist kein monolithisches System. Worker, Connector, Shop, Ameise und externe Schnittstellen kommunizieren über APIs und Datenbankstrukturen. Ein Wawi-Update kann die Erwartungen einer dieser Schnittstellen verändern, ohne dass die andere Seite automatisch nachzieht.

Das betrifft besonders den Connector: Wenn die Wawi eine neue API-Version für den Shop-Abgleich erwartet und der Connector im JTL-Shop noch die alte nutzt, schlägt der Verbindungstest fehl. Das ist kein Fehler im Update — es ist eine Kompatibilitätslücke, die bei der Update-Planung berücksichtigt werden muss. Laut JTL-Guide zur Aktualisierung empfiehlt JTL, nach einem Update alle verknüpften Systemkomponenten auf Kompatibilität zu prüfen.

Fehler in 30 Minuten statt 3 Stunden

Wer nach einem JTL Wawi Update sofort den richtigen Diagnoseweg geht — Ereignisprotokoll, Worker-Status, Connector-Verbindungstest — hat die meisten Probleme in 30 bis 60 Minuten identifiziert. Ohne diesen Weg suchen Händler oft stundenlang an der falschen Stelle: Wawi neu installieren, Server neu starten, Update rückgängig machen wollen. Aus unserer Praxis: Kunden die uns nach einem Update anrufen, haben die Ursache in der Regel innerhalb der ersten gemeinsamen 20 Minuten gefunden, weil wir den Diagnosebaum kennen.

Kein unnötiger Support-Aufwand bei bekannten Fehlern

Lizenzfehler und Worker-Probleme nach Updates sind keine Raritäten. Das sind dokumentierte Muster, für die es klare Lösungswege gibt. Wer den Worker-Dienst in der Windows-Dienstverwaltung neu startet statt Wawi zu deinstallieren, spart Zeit. Wer beim Lizenzfehler zuerst den Kundencenter-Account prüft statt die Lizenz neu zu kaufen, spart Geld. Unsere Erkenntnis aus Update-Begleitprojekten: Die teuersten Fehler entstehen nicht durch das Update — sie entstehen durch die falsche Reaktion auf das, was nach dem Update kommt.

Diese Reihenfolge haben wir aus echten Post-Update-Situationen abgeleitet. Geh jeden Punkt in dieser Reihenfolge durch — die meisten Probleme sind nach Schritt 2 oder 3 bereits identifiziert.

„Das Ereignisprotokoll in JTL Wawi erreichst du über Admin > Ereignisprotokoll. Es zeigt dir alle Fehler, Warnungen und Informationen aus dem laufenden Betrieb — sortiert nach Zeit. Nach einem Update suche gezielt nach roten Einträgen aus der letzten Stunde. Die Fehlermeldungen dort sind präziser als die Fehlerdialoge die beim Start erscheinen. Mit dem Fehlertext aus dem Protokoll kannst du gezielt im JTL Issue-Tracker suchen. Fast jeder bekannte Post-Update-Fehler hat dort einen dokumentierten Lösungsweg.“

„Öffne die Windows-Dienstverwaltung (Ausführen > services.msc) und suche nach dem JTL Worker Service. Wenn der Dienst als ‚Wird ausgeführt‘ angezeigt wird, aber im Wawi-Worker-Status-Fenster (Admin > JTL-Worker-Status) Fehler erscheinen, stoppe und starte den Dienst manuell neu. Danach in Wawi prüfen, ob die Aufgaben wieder sauber durchlaufen. Ein Neustart des Worker Services löst einen relevanten Teil aller Post-Update-Worker-Probleme.“

„Wenn ein Lizenzfehler erscheint, prüfe zuerst in Wawi unter Hilfe > Lizenzen, mit welchem Kundencenter-Account die Lizenz verknüpft ist. Dann prüfe im JTL-Kundencenter (kundencenter.jtl-software.de), ob die Lizenz auf denselben Account registriert ist. Das passiert zum Beispiel nach einem Serverwechsel oder wenn mehrere Kundencenter-Accounts vorhanden sind — und ist die häufigste Ursache für Lizenzfehler nach Updates. Das Kundencenter-Login-Passwort in Wawi neu eingeben und die Lizenz neu abrufen löst diesen Fehler in den meisten Fällen.“

„Wenn der Verbindungstest zum JTL-Shop nach dem Update fehlschlägt, prüfe die Connector-Version im JTL-Shop-Backend unter Admin > Connector. Die installierte Version muss mit der neuen Wawi-Version kompatibel sein. Aktuelle Kompatibilitätstabellen findest du im JTL-Guide unter Connector-Versionen. Wenn die Connector-Version veraltet ist, aktualisiere ihn über den JTL Extension Store. Danach Verbindungsdaten in Wawi neu eingeben und Verbindungstest starten.“

„Wenn Belege nach dem Update falsche Ausgaben zeigen — Positionen doppelt, fehlende Felder, unerwartete Kürzel — prüfe die betroffene Druckvorlage unter Einstellungen > Druckvorlagen. Teste mit einem Testdruck auf einen bekannten Auftrag. Wenn die Standardvorlage korrekt rendert, die eigene nicht, liegt das Problem in angepassten Feldreferenzen. Standardvorlage als Kopie anlegen und die eigene Anpassung schrittweise übertragen — das ist der sicherste Weg bei Druckvorlagen-Problemen.“