Timezone Bugs: Local Server Assumptions vs UTC-First (Prompts)
Twice a year, on two Sunday mornings, Copperline Transit sells seats on coaches that either do not exist or leave twice. The operator runs 312 departures a day, and 41 of them cross into the one neighbouring state that observes daylight saving while the home state does not.
Last March, 74 tickets were sold for a 02:15 departure that never ran, because that clock hour is skipped. In November the same route sold 31 seats twice, because the 01:40 hour happens twice and the system treated both as the same instant. The engineering ticket said “fix timezone bug”. The prompt behind the first patch said even less.
Two Weekends a Year, 38 Departures at Risk
The ticketing API stores departure times as a naive local timestamp, written from the station clock and read back with no zone attached. That works for 363 days. On the other two, the same stored value maps to two different instants, or to none.
What makes this class of bug expensive is that it is invisible in review. The code is short, the tests pass, the staging environment sits in the same zone as the office, and nothing fails until a customer stands at a bay at 02:10 in March holding a ticket for a coach that the timetable skipped.
- Nonexistent local times: the spring transition removes an hour. Any departure inside it has no valid instant.
- Ambiguous local times: the autumn transition repeats an hour. Any departure inside it has two valid instants.
- Border routes: the coach leaves a zone that does not shift and arrives in one that does, so the duration changes by an hour in one direction.
- Pricing: a fare tied to the wrong instant is either a refund or a chargeback, and both arrive weeks later.
A model can reason about all four cases. It will not do so unless the prompt names them, because the phrase “timezone bug” has a much cheaper interpretation: apply an offset and move on.
What the Naive Brief Returned
This is the prompt that produced the first patch, pasted with the endpoint attached.
Our ticketing API has a timezone bug. Departures are stored as local time
and converted with the server clock. Twice a year the times are wrong.
Fix it.
def departures(route_id, travel_date):
rows = db.query(route_id, travel_date)
return [{"id": r.id, "departs": r.depart_local} for r in rows]What came back: a 40-line patch that called the server clock, built a dictionary of month-to-offset values, and wrapped the conversion in a try/except that returned the original value on failure. No tests. No mention of the border stations. The comment above the new function read “handles DST”.
The month-to-offset dictionary is the tell. It is a guess dressed as a rule, and it breaks the moment a transition falls on an unexpected date. The try/except is worse: it silently returns a wrong instant instead of failing, which is why the November double sale reached production without an alert.
The prompt asked for a fix to a symptom. It never said where the time is stored, what the carriers send, which zones are involved, or what should happen to a departure that has no valid instant. Every one of those gaps was filled with the cheapest assumption available, and the cheapest assumption is always the server’s own clock.
If your interest is the general shape of these silent-failure patches, our comparison of error handling prompts covers the same pattern outside of dates.
The Brief That Puts UTC First
The second prompt does three things the first did not: it names the storage format, it demands an inventory of edge cases before any code, and it fixes a policy for each impossible case instead of leaving the choice to the model.
Role: senior backend engineer who has shipped scheduling systems across
daylight-saving boundaries.
Context: Copperline Transit runs 312 departures a day. 41 cross into a
neighbouring state that observes daylight saving; our home state does not.
Tickets are priced by departure instant. Storage is depart_local, a naive
timestamp written from the station clock. Carrier feeds arrive as ISO 8601
strings that include an offset.
Deliver in this order, and stop if step 1 finds a contradiction:
1. A table of every ambiguous and nonexistent local time in the next
12 months for the four border stations, with the recommended policy
for each row.
2. One paragraph on storing a UTC instant plus an IANA zone id, including
the migration cost for 312 daily rows.
3. A patch that never reads the server clock and never applies an offset
by hand.
4. One test per table row, each asserting an exact UTC instant, plus the
HTTP behaviour for the invalid case.
Constraints: standard library only, Python 3.11, zoneinfo. Nonexistent
local times are rejected, never shifted forward. Ambiguous local times
resolve to the first occurrence and are flagged in the response body.
Both cases return 422 with a machine-readable code. If a requirement
cannot be met, say which one and why before writing any code.What came back: first a table with 18 rows, covering the two transition Sundays at four stations plus the two arrival-only cases. Then a migration note: add a UTC column, backfill from the zone id, keep the local column for display and audit. Then a patch that resolved each local time through a zone object, rejected skipped times with a 422, and used the fold flag for the repeated hour. Then 18 tests, each with a literal UTC instant in the assertion.
The stop condition mattered. A model asked to “fix” will always produce code, even when the right answer is a schema change. A model told to stop on contradiction will tell you that the naive column cannot be repaired in place.
Three Clocks Inside One Ticket
Most timezone prompts fail because they treat time as one thing. A ticket carries three, and they disagree on purpose.
| Clock | What it answers | Failure when merged with another |
|---|---|---|
| Station clock | When staff and passengers see the coach leave | Border stops display the wrong hour after a transition |
| Schedule clock | Which service the timetable promises | A departure inside a skipped hour has no valid answer |
| Fare clock | Which instant the price is tied to | Refunds and double charges appear weeks later |
Once the three are separated, the prompt writes itself: the station clock is a display concern, the schedule clock needs a policy for impossible times, and the fare clock must be a UTC instant with no exceptions. Merging them into “the departure time” is what lets a single offset dictionary look like a solution.
This is also why “UTC everywhere” is an incomplete rule. Storing UTC is correct. Showing UTC to a passenger is not. The prompt has to say which layer converts, or the model will pick one and apply it to all three.
Adapting the Brief to Your Own Scheduler
Swap the domain and the skeleton holds. The four sections below are the minimum; dropping the edge-case inventory is what returns you to the first patch.
Role: [engineer with the specific production experience].
System: [volume, what one row represents, who reads the time].
Zones in play: [home zone], [zones that differ], [which observe DST].
Storage today: [column name, type, whether an offset is stored].
Feeds: [format of inbound timestamps and who sends them].
Step 1: list every ambiguous and nonexistent local time in the next
[period], for [the specific locations], with a policy per row.
Step 2: state the target schema and the migration cost in one paragraph.
Step 3: write the patch, with [named library or standard module].
Step 4: write one test per row, asserting exact instants.
Rules: no server clock, no manual offsets, [behaviour] for skipped times,
[behaviour] for repeated times, [status code and payload] for both.
If two requirements conflict, name the conflict before writing code.Two adjustments are worth making for almost any codebase. Set the test period to at least 12 months, because a table that stops at the next transition hides the return leg. And require exact instants in assertions rather than formatted strings, since a formatted string can look right while pointing at the wrong hour.
For the test-writing half of this, the structure in our unit test prompt guide pairs well with the inventory: generate the table first, then turn each row into a case.
Copperline now runs the brief before every timetable change, not just in March and November. The cost is one extra review step. The alternative was 74 refunds, 31 duplicated seats, and a support queue that could not explain either.
Sources & Notes
The three-clock framing, the four-step deliverable order, and the stop-on-contradiction rule are our own, reviewed on 2026-10-21. Copperline Transit, the 312 daily departures, the 41 border services, the 74 tickets, and the 31 duplicated seats are illustrative examples. Daylight-saving rules, transition dates, and zone identifiers change by jurisdiction and are revised by governments at short notice, so confirm them against a maintained timezone database rather than against a model’s memory. The Python details reference the standard library zoneinfo module as of Python 3.11; other runtimes use different APIs for the same concepts.
