Debugging Like a Jedi: Finding the Bug in the Force

The reporter faced a perplexing bug in a production report generation system that occurred every other Thursday at 2 AM, throwing a vague "value out of range" error and generating incomplete CSV files. The issue was intermittent, only appearing in the cloud environment, not on local testing.

The key insight was that the problem lay not in the code but in how the system handled dates during daylight saving time (DST) transitions. Specifically, the function calculating the due date treated naive datetime objects as UTC, which led to a one-hour discrepancy when DST shifted.

To solve the issue, the reporter adopted the "Observe → Hypothesize → Test → Learn" (OHTL) debugging framework, a method akin to a Jedi's precise and repeatable approach. By analyzing the data flow, the reporter discovered that the naive datetime object lost an hour when the server's US/Eastern timezone moved forward during DST.

The fix involved treating all datetimes as timezone-aware from the start, converting the input date to the target timezone (US/Eastern) before performing arithmetic, and using a library like zoneinfo (or pytz for older versions) to handle DST transitions properly. This change eliminated the intermittent failures by ensuring consistent datetime handling across time zones.

Implementing this approach not only resolved the specific bug but also provided a systematic method for tackling other flaky issues. By systematically observing symptoms, forming hypotheses, testing, and learning, the reporter turned a recurring nightmare into a solvable problem, demonstrating the power of a structured, methodical approach to debugging.