Der Fehler beginnt meistens mit einem Satz, der harmlos klingt
Die meisten Datums- und Zeitfehler beginnen nicht mit exotischer Astronomie. Sie beginnen mit einem Produktsatz, der offensichtlich wirkt: „Sende die Erinnerung morgen früh“, „lasse diese Testphase nach 30 Tagen ablaufen“, „zeige die heutigen Bestellungen“, „starte diesen Job um 2:30 Uhr“, „speichere den Timestamp“. Jeder Satz versteckt eine Regel. Morgen früh wo? Dreißig Kalendertage oder 30 mal 24 Stunden? Heute in der Stadt des Kunden, im Lager oder auf dem Datenbankserver? Was passiert, wenn 2:30 Uhr nicht existiert?
Software kann gut zählen. Kalender sind nicht nur Zählen. Sie bestehen aus menschlichen Konventionen: Zeitzonen, Sommerzeitwechsel, Arbeitstage, lokale Formate, Schaltjahre, ISO-Wochen, Datenbanktypen und rechtliche Stichtage. Fehler entstehen, wenn Code eine Ebene so behandelt, als wäre sie eine andere.
Dieser Leitfaden ist ein Praxismanual für die Fehler, die Produktionssysteme immer wieder beschädigen. Er richtet sich an Entwickler, Product Manager, Analysten und alle, die schon einmal auf ein Dashboard geschaut und sich gefragt haben, warum sich die Zahlen von gestern nach dem Frühstück verändert haben.
1. Naive Datetimes: der Timestamp ohne Pass
Eine naive Datetime ist ein Datum mit Uhrzeit, aber ohne Zeitzone. 2026-03-08 02:15 wirkt präzise, sagt aber nicht, wo es passiert ist. In New York existiert beim Sommerzeitwechsel im Frühjahr 2026 die Stunde von 02:00 bis 02:59 nicht. In einer anderen Stadt kann sie gültig sein. In UTC bedeutet sie wieder etwas anderes.
Der häufige Fehler ist, lokale Uhrzeit wie einen absoluten Zeitpunkt zu speichern. Ein Meeting für „9 Uhr Europe/Madrid“ soll auch dann 9 Uhr in Madrid bleiben, wenn Spanien die Uhren umstellt. Ein bereits passierter Zahlungsvorgang soll als Zeitpunkt gespeichert werden. Das sind unterschiedliche Modelle.
| Anwendungsfall | Speichern | Warum |
|---|---|---|
| Audit-Log, Klick, Zahlung, API-Ereignis | Zeitpunkt, meist UTC | Das Ereignis ist bereits in einem Moment passiert. |
| Zukünftiges Meeting in einer Stadt | Lokales Datum, lokale Uhrzeit, IANA-Zone | Die lokale Uhrzeit muss DST-Regeländerungen überstehen. |
| Geburtstag, Feiertag, Abrechnungstag | Nur Datum | Eine Tageszeit kann bedeutungslos sein. |
| Öffnungszeiten | Lokale Uhrzeit plus Ort oder Regel | Die Regel wiederholt sich in lokaler Zivilzeit. |
Wenn exakte Momente verglichen werden müssen, konvertieren Sie zu Zeitpunkten. Wenn ein menschlicher Termin an seinem beabsichtigten Ort erhalten bleiben soll, speichern Sie den Ort mit. Ein Offset wie UTC+01:00 reicht für zukünftige Planung nicht aus, weil sich der Offset ändern kann.
2. UTC-Verwirrung: gute Speicherung, schlechte Nutzererfahrung
„Alles in UTC speichern“ ist eine nützliche Regel für Ereignisse, die bereits passiert sind. Es ist aber kein vollständiges Produktdesign. Nutzer denken nicht in UTC, wenn sie einen Zahnarzttermin planen, ein Webinar veröffentlichen oder ein Hoteldatum auswählen. Sie denken in lokaler Zivilzeit.
Der Bug entsteht, wenn ein System UTC korrekt speichert, aber die beabsichtigte Zone des Nutzers verliert. Eine Einladung, die in Los Angeles für 9 Uhr erstellt wurde, kann intern als 17 Uhr UTC erscheinen. Das ist in Ordnung. Wenn die App das Ereignis später mit der Zeitzone des Servers rekonstruiert oder nur einen festen Offset speichert, kann sich das Meeting nach einer Zeitumstellung verschieben.
Gute Systeme trennen drei Fragen: Welcher Zeitpunkt ist das, welche lokale Uhrzeit wollte der Nutzer, und welche Zeitzonenregeln erklären diese lokale Uhrzeit? Unser Zeitzonenrechner ist genau deshalb nützlich, weil Datum, Ort und Offset zusammen zählen.
3. DST-Lücken und Folds: Zeiten, die verschwinden oder zweimal passieren
Sommerzeit erzeugt zwei klassische Fallen. Im Frühjahr kann eine lokale Stunde übersprungen werden. Im Herbst kann eine lokale Stunde zweimal vorkommen. Wenn ein Scheduler „2026-03-08 02:30 America/New_York“ akzeptiert, was soll er tun? Ablehnen? Auf 03:00 verschieben? In einer anderen Zone interpretieren? Es gibt keine universell richtige Antwort. Das Produkt braucht eine Regel.
Mehrdeutige Herbstzeiten sind noch subtiler. „2026-11-01 01:30 America/New_York“ kann die erste 01:30 oder die zweite 01:30 meinen. Beide lokalen Labels sind real. Logs, Verkehrssysteme, Krankenhaussysteme und Job-Scheduler müssen wissen, welche gemeint ist.
Eine sinnvolle Testsuite enthält echte Umstellungsdaten für die Zonen Ihrer Nutzer. Testen Sie nicht nur den 15. Januar. Testen Sie einen Spring-forward-Tag, einen Fall-back-Tag und ein Land, dessen DST-Regeln sich von Ihren eigenen unterscheiden.
4. Nur-Datum-Werte, die versehentlich zu Mitternacht werden
Ein Datum ist nicht immer eine Datetime mit angehängter Mitternacht. Eine Hotelbuchung für den 3. Juni, ein Geburtstag, ein Steuertermin und ein Feiertag sind Datumsbegriffe. Wenn Code daraus 2026-06-03T00:00:00Z macht, hat er eine Uhrzeit und eine Zone erfunden.
So verschieben sich Geburtstage für Nutzer westlich von UTC auf den Vortag. So kann auch ein „heutiger Bericht“ für ein Team gestrige Daten und für ein anderes morgige Daten zeigen. Die Lösung ist einfach: Verwenden Sie Nur-Datum-Typen für Nur-Datum-Konzepte, und erzeugen Sie eine Datetime erst, wenn die Geschäftsregel wirklich eine Uhrzeit braucht.
Bei Fristen hilft eine präzisere Frage: Läuft der Eintrag zu Beginn des Datums, am Ende des Datums, zum lokalen Geschäftsschluss oder zu einem exakten Zeitpunkt ab? „Läuft am 3. Juni ab“ ist Produkttext, keine vollständige Regel.
5. Tage als Sekunden addieren
86.400 Sekunden zu addieren ist nicht dasselbe wie einen lokalen Kalendertag zu addieren. Die meisten Tage haben 24 Stunden, aber DST-Übergangstage können 23 oder 25 Stunden haben. Wenn eine tägliche Erinnerung um 8 Uhr lokaler Zeit erscheinen soll, addieren Sie einen Kalendertag in der Zone des Nutzers. Wenn ein Cache exakt nach 24 Stunden ablaufen soll, addieren Sie eine Dauer.
| Formulierung | Bedeutet meist | Sichereres Modell |
|---|---|---|
| Gleiche Uhrzeit morgen | Nächster lokaler Kalendertag zur gleichen Wandzeit | Datum/Uhrzeit in Nutzerzone |
| Läuft in 24 Stunden ab | Exakt verstrichene Dauer | Zeitpunkt plus Dauer |
| Fällig in 3 Arbeitstagen | Lokale Arbeitstagsregel | Arbeitskalender |
| Jeden Montag um 9 | Wiederkehrender lokaler Termin | Lokale Uhrzeit plus IANA-Zone |
Darum ist ein Arbeitstage-Rechner nicht einfach ein Datumsdifferenz-Rechner ohne Wochenenden. Feiertage, lokale Wochenenden und beobachtete Schließtage können das Ergebnis verändern.
6. Unix-Timestamp-Einheiten: Sekunden, Millisekunden, Mikrosekunden, Nanosekunden
Unix-Zeit ist elegant: Zeit seit 1970-01-01T00:00:00Z zählen. Das Problem ist, dass Software-Ökosysteme unterschiedliche Einheiten verwenden. Viele APIs nutzen Sekunden. JavaScript nutzt Millisekunden. Einige Datenbanken und Observability-Systeme nutzen Mikrosekunden oder Nanosekunden. 1717425600 und 1717425600000 beschreiben denselben Moment in verschiedenen Einheiten; mit der falschen Einheit springt das Datum um Jahrhunderte.
Der schnellste Plausibilitätscheck ist die Ziffernzahl. Aktuelle Unix-Sekunden haben 10 Ziffern. Millisekunden haben 13. Mikrosekunden 16. Nanosekunden 19. Ein guter Importer sollte die Einheit explizit erkennen oder mehrdeutige Eingaben ablehnen, statt still zu raten. Unser Unix-Timestamp-Konverter zeigt dieselbe Idee als Werkzeug.
7. Datumswerte im falschen Format als Strings sortieren
ISO-ähnliche Daten sortieren als Text gut: 2026-06-03 kommt vor 2026-12-01. Viele lokale Formate tun das nicht. Eine Liste aus MM/DD/YYYY- oder DD/MM/YYYY-Strings kann in einer kleinen Stichprobe korrekt aussehen und scheitern, sobald Monate oder Länder wechseln.
Verwenden Sie ISO 8601 oder echte Datumstypen für Austausch und Speicherung. Lokalisierte Formate gehören an die Anzeigegrenze. Wenn eine CSV für Menschen gedacht ist, nennen Sie das erwartete Format in der Kopfzeile oder Exportdokumentation. Wenn sie für Maschinen gedacht ist, bevorzugen Sie für Timestamps einen eindeutigen Standard wie RFC 3339.
8. Wochennummern-Bugs rund um Neujahr
Wochennummern sind nicht universell. ISO-Wochen beginnen am Montag, und Woche 1 ist die Woche mit dem ersten Donnerstag. Einige US-artige Systeme beginnen am Sonntag und zählen die Woche mit dem 1. Januar als Woche 1. Rund um Neujahr können diese Regeln um eine ganze Woche auseinanderliegen.
Wenn ein Bericht „Umsatz Woche 1“ sagt, ein Payroll-Export „2026-W01“ enthält und eine Tabellenkalkulation ihre Standardfunktion nutzt, klären Sie die Regel, bevor Zahlen abgeglichen werden. Für internationale Teams ist die sicherste Beschriftung das Wochensystem plus Datumsbereich, etwa: „ISO 2026-W01, 29. Dez. 2025-4. Jan. 2026“.
Dieselbe Logik steckt in unserem Kalenderwochen-Tool, das den Datumsbereich anzeigt, statt die Nummer für selbsterklärend zu halten.
9. Server-Zeitzonen, die in die Anwendung durchsickern
Einer der frustrierendsten Produktionsfehler ist Code, der lokal jeden Test besteht und nach dem Deployment scheitert, weil der Server in einer anderen Zeitzone läuft. Entwickler-Laptop, CI-Runner, Docker-Image, Datenbank, Queue-Worker und Analytics-Warehouse können alle verschiedene Defaults haben.
Setzen Sie explizite Zeitzonen in Tests. Führen Sie mindestens einen Testjob mit einer nicht lokalen Zeitzone aus. Vermeiden Sie Prozess-Defaults beim Parsen oder Formatieren. Wenn eine Funktion einen Datumsstring erhält, müssen erwartetes Format und Zone Teil des Vertrags sein.
10. „Ende des Tages“ ohne Ort
Ende des Tages klingt klar, bis Kunden an mehr als einem Ort leben. Eine Aktion, die „Freitag um Mitternacht“ endet, kann lokale Mitternacht des Kunden, Mitternacht am Firmensitz, UTC-Mitternacht oder den Cut-off des Zahlungsanbieters bedeuten. Jede Regel erzeugt eine andere Nutzererfahrung.
Guter Produkttext nennt den Ort oder nutzt einen Countdown, der an die tatsächliche Frist gebunden ist. Guter Backend-Code speichert die Frist als präzisen Zeitpunkt, nachdem die Geschäftsregel angewendet wurde. Gute Support-Dokumentation sagt, welche Regel verwendet wurde.
Praktische Checkliste vor dem Shipping von Datums-/Zeitcode
- Ist dieser Wert ein Zeitpunkt, lokale Datum/Uhrzeit, Nur-Datum-Wert, Dauer oder Wiederholungsregel?
- Wenn er lokal ist, welche IANA-Zeitzone besitzt die Regel?
- Wenn es ein Nur-Datum-Wert ist, wurde vermieden, UTC-Mitternacht zu erfinden?
- Haben DST-Lücken und doppelte Stunden explizites Verhalten?
- Sind Timestamp-Einheiten benannt, validiert und getestet?
- Definieren Berichte Wochensystem und Datumsbereich?
- Laufen Tests außerhalb der Zeitzone des Entwicklers?
- Sagt der sichtbare Text genug, damit ein Mensch korrekt handeln kann?
Die tiefere Regel
Datums- und Zeitfehler entstehen selten durch fehlenden raffinierten Code. Sie entstehen durch ein fehlendes Substantiv. „Morgen“ braucht einen Ort. „Dreißig Tage“ muss Kalender oder Dauer sagen. „Woche 1“ braucht ein System. „Timestamp“ braucht eine Einheit. „Ende des Tages“ braucht eine Jurisdiktion oder Zeitzone.
Wenn dieses Substantiv explizit ist, wird der Code meist einfacher. Die Datenbankspalte bekommt den richtigen Typ. Der API-Vertrag überrascht weniger. Die UI kann das Ergebnis erklären. Und die nächste Person, die den Code liest, muss nicht rekonstruieren, was „jetzt plus ein Tag“ bedeuten sollte.